ES-52: updated UpdateAction to act same as insert or gets for 'retryable server errors'

Add isEnabled method to meta-data producers; Put interface on top of …

.circleci/adjust-pom-version.sh

@@ -0,0 +1,23 @@
+#!/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
+
+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.";
+   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')
+fi
+
+POM=$(dirname $0)/../pom.xml
+
+echo "Updating $POM <revision> to: $SLUG-SNAPSHOT"
+sed -i "s/<revision>.*/<revision>$SLUG-SNAPSHOT<\/revision>/" $POM
+git diff $POM

.circleci/config.yml

@@ -1,7 +1,6 @@
 version: 2.1
 
 orbs:
-  slack: circleci/slack@4.10.1
   localstack: localstack/platform@1.0
 
 commands:
@@ -12,8 +11,10 @@ commands:
     steps:
       - store_artifacts:
           path: << parameters.module >>/target/site/jacoco/index.html
+          when: always
       - store_artifacts:
           path: << parameters.module >>/target/site/jacoco/jacoco-resources
+          when: always
 
   install_java17:
     steps:
@@ -24,6 +25,12 @@ commands:
             sudo apt install -y openjdk-17-jdk
             sudo rm /etc/alternatives/java
             sudo ln -s /usr/lib/jvm/java-17-openjdk-amd64/bin/java /etc/alternatives/java
+      - run:
+          ## used by jacoco uncovered class reporting in pom.xml
+          name: Install html2text
+          command: |
+            sudo apt-get update
+            sudo apt-get install -y html2text
 
   mvn_verify:
     steps:
@@ -45,10 +52,18 @@ commands:
           module: qqq-backend-module-filesystem
       - store_jacoco_site:
           module: qqq-backend-module-rdbms
+      - store_jacoco_site:
+          module: qqq-backend-module-api
+      - store_jacoco_site:
+          module: qqq-middleware-api
       - store_jacoco_site:
           module: qqq-middleware-javalin
       - store_jacoco_site:
           module: qqq-middleware-picocli
+      - store_jacoco_site:
+          module: qqq-middleware-slack
+      - store_jacoco_site:
+          module: qqq-language-support-javascript
       - store_jacoco_site:
           module: qqq-sample-project
       - run:
@@ -67,6 +82,10 @@ commands:
   mvn_jar_deploy:
     steps:
       - checkout
+      - run:
+          name: Adjust pom version
+          command: |
+            .circleci/adjust-pom-version.sh
       - restore_cache:
           keys:
             - v1-dependencies-{{ checksum "pom.xml" }}
@@ -83,27 +102,23 @@ jobs:
   mvn_test:
     executor: localstack/default
     steps:
-      - localstack/startup
+      ## - localstack/startup
       - install_java17
       - mvn_verify
-      - slack/notify:
-          event: fail
 
   mvn_deploy:
     executor: localstack/default
     steps:
-      - localstack/startup
+      ## - localstack/startup
       - install_java17
       - mvn_verify
       - mvn_jar_deploy
-      - slack/notify:
-          event: always
 
 workflows:
   test_only:
     jobs:
       - mvn_test:
-          context: [ qqq-maven-registry-credentials, kingsrook-slack, build-qqq-sample-app ]
+          context: [ qqq-maven-registry-credentials, build-qqq-sample-app ]
           filters:
             branches:
               ignore: /dev/
@@ -113,7 +128,7 @@ workflows:
   deploy:
     jobs:
       - mvn_deploy:
-          context: [ qqq-maven-registry-credentials, kingsrook-slack, build-qqq-sample-app ]
+          context: [ qqq-maven-registry-credentials, build-qqq-sample-app ]
           filters:
             branches:
               only: /dev/

README.md

@@ -10,7 +10,7 @@ The bundle contains all of the sub-jars.  It is named:
 
 ```qqq-${version}.jar```
 
-You can also use fine grained jars:
+You can also use fine-grained jars:
 - `qqq-backend-core`: The core module.  Useful if you're developing other modules.
 - `qqq-backend-module-rdbms`: Backend module for working with Relational Databases.
 - `qqq-backend-module-filesystem`: Backend module for working with Filesystems (including AWS S3).

checkstyle/config.xml

@@ -262,6 +262,7 @@
    <module name="Header">
      <property name="headerFile" value="checkstyle/license.txt"/>
      <property name="fileExtensions" value="java"/>
+     <property name="ignoreLines" value="3"/>
    </module>
    <module name="SuppressWarningsFilter"/>
 </module>

docs/Introduction.adoc

@@ -0,0 +1,8 @@
+= Introduction
+
+QQQ is ...
+
+- Framework
+- Declarative
+- Easy thing easy; Hard thing possible
+- Customizable

docs/actions/QueryAction.adoc

@@ -0,0 +1,179 @@
+== QueryAction
+include::../variables.adoc[]
+
+The `*QueryAction*` is the basic action that is used to get records from a {link-table}.
+In SQL/RDBMS terms, it is analogous to a `SELECT` statement, where 0 or more records may be found and returned.
+
+=== Examples
+==== Basic Form
+[source,java]
+----
+QueryInput input = new QueryInput(qInstance);
+input.setSession(session);
+input.setTableName("orders");
+input.setFilter(new QQueryFilter()
+   .withCriteria(new QFilterCriteria("total", GREATER_THAN, new BigDecimal("3.50")))
+   .withOrderBy(new QFilterOrderBy("orderDate", false))
+);
+QueryOutput output = new QueryAction.execute(input);
+List<QRecord> records = output.getRecords();
+----
+
+=== QueryInput
+* `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.
+* `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.
+* `recordPipe` - *RecordPipe object* - Optional object that records are placed into, for asynchronous processing.
+** If a *recordPipe* is used, then records cannot be retrieved from the *QueryOutput*.
+Rather, such records must be read from the pipe's `consumeAvailableRecords()` method.
+** A *recordPipe* should only be used when a *QueryAction* is running in a separate Thread from the record's consumer.
+* `shouldTranslatePossibleValues` - *boolean, default: false* - Controls whether any fields in the table with a *possibleValueSource* assigned to them should have those possible values looked up
+(e.g., to provide text translations in the generated records' `displayValues` map).
+** For example, if running a query to present results to a user, this would generally need to be *true*.
+But if running a query to provide data as part of a process, then this can generally be left as *false*.
+* `shouldGenerateDisplayValues` - *boolean, default: false* - Controls whether if field level *displayFormats* should be used to populate the generated records' `displayValues` map.
+** For example, if running a query to present results to a user, this would generally need to be *true*.
+But if running a query to provide data as part of a process, then this can generally be left as *false*.
+* `queryJoins` - *List of QueryJoin objects* - Optional list of tables to be joined with the main *table* specified in the *QueryInput*.
+See QueryJoin below for further details.
+
+==== 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`).
+
+* `criteria` - *List of QFilterCriteria* - Individual conditions or clauses to filter records.
+They are combined using the *booleanOperator* specified in the *QQueryFilter*.  See below for further details.
+* `orderBys` - *List of QFilterOrderBy* - List of fields (and directions) to control the sorting of query results.
+In general, multiple *orderBys* can be given (depending on backend implementations).
+* `booleanOperator` - *Enum of AND, OR, default: AND* - Specifies the logical joining operator used among individual criteria.
+* `subFilters` - *List of QQueryFilter* - To build arbitrarily complex queries, with nested boolean logic, 0 or more *subFilters* may be provided.
+** 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*
+
+[source,java]
+----
+ queryInput.setFilter(new QQueryFilter()
+    .withBooleanOperator(OR)
+    .withSubFilters(List.of(
+       new QQueryFilter().withBooleanOperator(AND)
+          .withCriteria(new QFilterCriteria("firstName", EQUALS, "James"))
+          .withCriteria(new QFilterCriteria("lastName", EQUALS, "Maes")),
+       new QQueryFilter().withBooleanOperator(AND)
+          .withCriteria(new QFilterCriteria("firstName", EQUALS, "Darin"))
+          .withCriteria(new QFilterCriteria("lastName", EQUALS, "Kelkhoff"))
+    )));
+
+// which would generate the following WHERE clause in an RDBMS backend:
+   WHERE (first_name='James' AND last_name='Maes') OR (first_name='Darin' AND last_name='Kelkhoff')
+----
+
+===== QFilterCriteria
+* `fieldName` - *String, required* - Reference to a field on the table being queried.
+** Or, in the case of a query with *queryJoins*, a qualified name of a field from a join-table (where the qualifier would be the joined table's name or alias, followed by a dot)
+*** For example:  `orderLine.sku` or `orderBillToCustomer.firstName`
+* `operator` - *Enum of QCriteriaOperator, required* - Comparison operation to be applied to the field specified as *fieldName* and the *values* or *otherFieldName*.
+** e.g., `EQUALS`, `NOT_IN`, `GREATER_THAN`, `BETWEEN`, `IS_BLANK`, etc.
+* `values` - *List of values, conditional* - Provides the value(s) that the field is compared against.
+The number of values (0, 1, 2, or more) be driven based on the *operator* being used.
+If an *otherFieldName* is given, and the *operator* expects 1 value, then *values* is ignored, and *otherFieldName* is used.
+* `otherFieldName` - *String, conditional* - Specifies that the *fieldName* should be compared against another field in the records, rather than the values in the *values* property.
+Only used for *operators* that expect 1 value (e.g., `EQUALS` or `LESS_THAN_OR_EQUALS` - not `IS_NOT_BLANK` or `IN`).
+
+QFilterCriteria definition examples:
+[source,java]
+----
+// one-liners, via constructors that take (List<Serializable> values) or (Serializable... values) in 3rd position
+new QFilterCriteria("id", IN, List.of(1, 2, 3))
+new QFilterCriteria("name", IS_BLANK)
+new QFilterCriteria("orderNo", IN, orderNoList)
+new QFilterCriteria("state", EQUALS, "MO");
+
+// long-form, with fluent setters
+new QFilterCriteria()
+   .withFieldName("quantity")
+   .withOpeartor(QCriteriaOperator.GREATER_THAN)
+   .withValues(List.of(47));
+
+// to use otherFieldName, long-form must be used
+new QFilterCriteria()
+   .withFieldName("firstName")
+   .withOpeartor(QCriteriaOperator.EQUALS)
+   .withOtherFieldName("lastName");
+
+// using otherFieldName to build a criterion that looks at two fields from join tables
+new QFilterCriteria()
+   .withFieldName("billToCustomer.lastName")
+   .withOpeartor(QCriteriaOperator.NOT_EQUALS)
+   .withOtherFieldName("shipToCustomer.lastName");
+
+----
+
+===== QFilterOrderBy
+* `fieldName` - *String, required* - Reference to a field on the table being queried.
+** Or, in the case of a query with *queryJoins*, a qualified name of a field from a join-table (where the qualifier would be the joined table's name or alias, followed by a dot)
+* `isAscending` - *boolean, default: true* - Specify if the sort is ascending or descending.
+
+QFilterCriteria definition examples:
+
+[source,java]
+----
+// short-form, via constructors
+new QFilterOrderBy("id") // isAscending defaults to true.
+new QFilterOrderBy("name", false)
+
+// long-form, with fluent setters
+new QFilterOrderBy()
+   .withFieldName("birthDate")
+   .withIsAscending(true);
+----
+
+==== QueryJoin
+* `joinTable` - *String, required* - Name of the table that is being joined in to the existing query.
+** Will be inferred from *joinMetaData*, if *joinTable* is not set when *joinMetaData* gets set.
+* `baseTableOrAlias` - *String, required* - Name of a table (or an alias) already defined in the query, to which the *joinTable* will be joined.
+** Will be inferred from *joinMetaData*, if *baseTableOrAlias* is not set when *joinMetaData* gets set (which will only use the leftTableName from the joinMetaData - never an alias).
+* `joinMetaData` - *QJoinMetaData object* - Optional specification of a {link-join} in the current QInstance.
+If not set, will be looked up at runtime based on *baseTableOrAlias* and *joinTable*.
+** If set before *baseTableOrAlias* and *joinTable*, then they will be set based on the *leftTable* and *rightTable* in this object.
+* `alias` - *String* - Optional (unless multiple instances of the same table are being joined together, when it becomes required).
+Behavior based on SQL `FROM` clause aliases.
+If given, must be used as the part before the dot in field name specifications throughout the rest of the query input.
+* `select` - *boolean, default: false* - Specify whether fields from the *rightTable* should be selected by the query.
+If *true*, then the `QRecord` objects returned by this query will have values with corresponding to the (table-or-alias `.` field-name) form.
+* `type` - *Enum of INNER, LEFT, RIGHT, FULL, default: INNER* - specifies the SQL-style type of join being performed.
+
+QueryJoin definition examples:
+
+[source,java]
+----
+// selecting from an "orderLine" table - then join to its corresponding "order" table
+queryInput.withTableName("orderLine");
+queryInput.withQueryJoin(new QueryJoin("order").withSelect(true));
+...
+queryOutput.getRecords().get(0).getValueBigDecimal("order.grandTotal");
+
+// given an "order" table with 2 foreign keys to a customer table (billToCustomerId and shipToCustomerId)
+// Note, we must supply the JoinMetaData to the QueryJoin, to drive what fields to join on in each case.
+queryInput.withTableName("order");
+queryInput.withQueryJoins(List.of(
+   new QueryJoin(instance.getJoin("orderJoinShipToCustomer")
+       .withAlias("shipToCustomer")
+       .withSelect(true)),
+   new QueryJoin(instance.getJoin("orderJoinBillToCustomer")
+       .withAlias("billToCustomer")
+       .withSelect(true))));
+...
+record.getValueString("billToCustomer.firstName")
+   + " placed an order for "
+   + record.getValueString("shipToCustomer.firstName")
+
+----
+
+=== QueryOutput
+* `records` - *List of QRecord* - List of 0 or more records that match the query filter.
+** _Note:  If a *recordPipe* was supplied to the QueryInput, then calling `queryOutput.getRecords()` will result in an `IllegalStateException` being thrown - as the records were placed into the pipe as they were fetched, and cannot all be accessed as a single list._

docs/actions/RenderTemplateAction.adoc

@@ -0,0 +1,33 @@
+== RenderTemplateAction
+include::../variables.adoc[]
+
+The `*RenderTemplateAction*` performs the job of taking a template - that is, a string of code, in a templating language, such as https://velocity.apache.org/engine/1.7/user-guide.html[Velocity], and merging it with a set of data (known as a context), to produce some using-facing output, such as a String of HTML.
+
+=== Examples
+==== Canonical Form
+[source,java]
+----
+RenderTemplateInput input = new RenderTemplateInput(qInstance);
+input.setSession(session);
+input.setCode("Hello, ${name}");
+input.setTemplateType(TemplateType.VELOCITY);
+input.setContext(Map.of("name", "Darin"));
+RenderTemplateOutput output = new RenderTemplateAction.execute(input);
+String result = output.getResult();
+assertEquals("Hello, Darin", result);
+----
+
+==== Convenient Form
+[source,java]
+----
+String result = RenderTemplateAction.renderVelocity(input, Map.of("name", "Darin"), "Hello, ${name}");
+assertEquals("Hello, Darin", result);
+----
+
+=== RenderTemplateInput
+* `code` - *String, Required* - String of template code to be rendered, in the templating language specified by the `type` parameter.
+* `type` - *Enum of VELOCITY, Required* - Specifies the language of the template code.
+* `context` - *Map of String → Object* - Data to be made available to the template during rendering.
+
+=== RenderTemplateOutput
+* `result` - *String* - Result of rendering the input template and context.

docs/docinfo.html

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

docs/index.adoc

@@ -0,0 +1,17 @@
+= QQQ
+:doctype: book
+:toc: left
+:source-highlighter: coderay
+
+include::Introduction.adoc[leveloffset=+1]
+
+== Meta Data
+include::metaData/Tables.adoc[leveloffset=+1]
+''''
+include::metaData/Reports.adoc[leveloffset=+1]
+
+== Actions
+include::actions/QueryAction.adoc[leveloffset=+1]
+''''
+include::actions/RenderTemplateAction.adoc[leveloffset=+1]
+''''

docs/metaData/Fields.adoc

@@ -0,0 +1,24 @@
+== QQQ Fields
+include::../variables.adoc[]
+
+QQQ Fields define
+
+=== QFieldMetaData
+*QFieldMetaData Properties:*
+
+* `name` - *String, Required* - Unique name for the field within its container (table, process, etc).
+* `label` - *String* - User-facing label for the field, presented in User Interfaces.
+* `type` - *enum of QFieldType, Required* - Data type for values in the field.
+* `backendName` - *String* - Name of the field within its backend.
+** For example, in an RDBMS-backed table, a field's `name` may be written in camel case, but its `backendName` written with underscores.
+* `isRequired` - *boolean, default false* - Indicator that a value is required in this field.
+* `isEditable` - *boolean, default true* - Indicator that users may edit values in this field.
+* `displayFormat` - *String, default `%s`* - Java Format Specifier string, used to format values in the field for display in user interfaces.
+Used to set values in the `displayValues` map within a `QRecord`.
+** Recommended values for `displayFormat` come from the `DisplayFormat` interface, such as `DisplayFormat.CURRENCY`, `DisplayFormat.COMMAS`, or `DisplayFormat.DECIMAL2_COMMAS`.
+* `defaultValue` - Value to use for the field if no other value is given.  Type is based on the field's `type`.
+* `possibleValueSourceName` - *String* - Reference to a {link-pvs} to be used for this field.
+Values in this field should correspond to ids from the referenced Possible Value Source.
+* `maxLength` - *Integer* - Maximum length (number of characters) allowed for values in this field.
+Only applicable for fields with `type=STRING`.
+* `

docs/metaData/Reports.adoc

@@ -0,0 +1,173 @@
+== QQQ Reports
+include::../variables.adoc[]
+
+QQQ can generate reports based on {link-tables} defined within a QQQ Instance.
+Users can run reports, providing input values.
+Alternatively, application code can run reports as needed, supplying input values.
+
+=== QReportMetaData
+Reports are defined in a QQQ Instance with a `*QReportMetaData*` object.
+Reports are defined in terms of their sources of data (`QReportDataSource`), and their view(s) of that data (`QReportView`).
+
+*QReportMetaData Properties:*
+
+* `name` - *String, Required* - Unique name for the report within the QQQ Instance.
+* `label` - *String* - User-facing label for the report, presented in User Interfaces.
+Inferred from `name` if not set.
+* `processName` - *String* - Name of a {link-process} used to run the report in a User Interface.
+* `inputFields` - *List of {link-field}* - Optional list of fields used as input to the report.
+** The values in these fields can be used via the syntax `${input.NAME}`, where `NAME` is the `name` attribute of the `inputField`.
+** For example:
+
+[source,java]
+----
+// given this inputField:
+new QFieldMetaData("storeId", QFieldType.INTEGER)
+
+// its run-time value can be accessed, e.g., in a query filter under a data source:
+new QFilterCriteria("storeId", QCriteriaOperator.EQUALS, List.of("${input.storeId}"))
+
+// or in a report view's title or field formulas:
+.withTitleFields(List.of("${input.storeId}"))
+new QReportField().withName("storeId").withFormula("${input.storeId}")
+----
+
+* `dataSources` - *List of QReportDataSource, Required* - Definitions of the sources of data for the report.
+At least one is required.
+
+==== QReportDataSource
+Data sources for QQQ Reports can either reference {link-tables} within the QQQ Instance, or they can provide custom code in the form of a `CodeReference` to a  `Supplier`, for use cases such as a static data tab in an Excel report.
+
+*QReportDataSource Properties:*
+
+* `name` - *String, Required* - Unique name for the data source within its containing Report.
+* `sourceTable` - *String, Conditional* - Reference to a {link-table} in the QQQ Instance, which the data source queries data from.
+* `queryFilter` - *QQueryFilter* - If a `sourceTable` is defined, then the filter specified here is used to filter and sort the records queried from that table when generating the report.
+* `staticDataSupplier` - *QCodeReference, Conditional* - Reference to custom code which can be used to supply the data for the data source, as an alternative to querying a `sourceTable`.
+** Must be a `JAVA` code type
+** Must be a `REPORT_STATIC_DATA_SUPPLIER` code usage.
+** The referenced class must implement the interface: `Supplier<List<List<Serializable>>>`.
+
+==== QReportView
+Report Views control how the source data for a report is organized and presented to the user in the output report file.
+If a DataSource describes the rows for a report (e.g., what table provides what records), then a View may be thought of as describing the columns in the report.
+A single report can have multiple views, specifically, for the use-case where an Excel file is being generated, in which case each View creates a tab or sheet within the `xlsx` file.
+
+*QReportView Properties:*
+
+* `name` - *String, Required* - Unique name for the view within its containing Report.
+* `label` - *String* - Used as a sheet (tab) label in Excel formatted reports.
+* `type` - *enum of TABLE, SUMMARY, PIVOT. Required* - Defines the type of view being defined.
+** *TABLE* views are a simple listing of the records from the data source.
+** *SUMMARY* views are essentially pre-computed Pivot Tables.
+That is to say, the aggregation done by a Pivot Table in a spreadsheet file is done by QQQ while generating the report.
+In this way, a non-spreadsheet report (e.g., PDF or CSV) can have summarized data, as though it were a Pivot Table in a live spreadsheet.
+** *PIVOT* views produce actual Pivot Tables, and are only supported in Excel files _(and are not supported at the time of this writing)_.
+* `dataSourceName` - *String, Required* - Reference to a DataSource within the report, that is used to provide the rows for the view.
+* `varianceDataSourceName` - *String* - Optional reference to a second DataSource within the report, that is used in `*SUMMARY*` type views for computing variances.
+** For example, given a Data Source with a filter that selects all sales records for a given year, a Variance Data Source may have a filter that selects the previous year, for doing comparissons.
+* `pivotFields` - *List of String, Conditional* - For *SUMMARY* or *PIVOT* type views, specify the field(s) used as pivot rows.
+** For example, in a summary view of orders, you may "pivot" on the *customerId* field, to produce one row per-customer, with aggregate data for that customer.
+* `titleFormat` - *String* - Java Format String, used with `titleFields` (if given), to produce a title row, e.g., first row in the view (before any rows from the data source).
+* `titleFields` - *List of String, Conditional* - Used with `titleFormat`, to provide values for any format specifiers in the format string.
+Syntax to reference a field (e.g., from a report input field) is: `${input.NAME}`, where `NAME` is the `name` attribute of the inputField.
+** Example of using `titleFormat` and `titleFields`:
+
+[source,java]
+----
+// given these inputFields:
+new QFieldMetaData("startDate", QFieldType.DATE)
+new QFieldMetaData("endDate", QFieldType.DATE)
+
+// a view can have a title row like this:
+.withTitleFormat("Weekly Sales Report - %s - %s")
+.withTitleFields(List.of("${input.startDate}", "${input.endDate}"))
+----
+
+* `includeHeaderRow` - *boolean, default true* - Indication that first row of the view should be the column labels.
+** If true, then header row is put in the view.
+** If false, then no header row is put in the view.
+* `includeTotalRow` - *boolean, default false* - Indication that a totals row should be added to the view.
+All numeric columns are summed to produce values in the totals row.
+** If true, then totals row is put in the view.
+** If false, then no totals row is put in the view.
+* `includePivotSubTotals` - *boolean, default false* - For a *SUMMARY* or *PIVOT* type view, if there are more than 1 *pivotFields* being used, this field is an indication that each higher-level pivot should include sub-totals.
+** #TODO - provide example#
+* `columns` - *List of QReportField, required* - Definition of the columns to appear in the view.  See section on QReportField for details.
+* `orderByFields` - *List of QFilterOrderBy, optional* - For a *SUMMARY* or *PIVOT* type view, how to sort the rows.
+* `recordTransformStep` - *QCodeReference, subclass of `AbstractTransformStep`* - Custom code reference that can be used to transform records after they are queried from the data source, and before they are placed into the view.
+Can be used to transform or customize values, or to look up additional values to add to the report.
+** #TODO - provide example#
+* `viewCustomizer` - *QCodeReference, implementation of interface `Function<QReportView, QReportView>`* - Custom code reference that can be used to customize the report view, at runtime.
+Can be used, for example, to dynamically define the report's *columns*.
+** #TODO - provide example#
+
+===== QReportField
+Report Fields define the fields (AKA columns) of data that appear in a report view.
+These fields can either be direct references to fields from the report's data sources, or values computed using formula defined in the QReportField.
+
+*QReportField Properties:*
+
+* `name` - *String, required* - Unique identifier for the field within its ReportView.
+In general, will be a reference to a field from the ReportView's DataSource *unless a *formula* is given (for *SUMMARY* type views), the field is marked as *isVirtual*, or the field is marked as *showPossibleValueLabel*).
+* `label` - *String* - Optional text label to identify the field, for example, in a header row.
+If not given, may be derived from field, where possible.
+* `type` - *QFieldType*
+* `formula` - *String, conditional* - Required for *SUMMARY* type views.
+Defines the formula to be used for computing the value in this field.
+** For example:
+
+[source,java]
+----
+.withName("reportEndDate").withFormula("${input.endDate}")
+
+.withName("count").withFormula("${pivot.count.id}")
+
+.withName("percentOfTotal").withFormula("=DIVIDE(${pivot.count.id},${total.count.id})")
+
+.withName("sumCost").withFormula("${pivot.sum.cost}")
+
+.withName("sumCharge").withFormula("${pivot.sum.charge}")
+
+.withName("profit").withFormula("=MINUS(${pivot.sum.charge},${pivot.sum.cost})")
+
+.withName("totalCost").withFormula("=DIVIDE_SCALE(${pivot.sum.cost},${pivot.count.id},2)")
+
+.withName("revenuePer").withFormula("=DIVIDE_SCALE(${pivot.sum.charge},${pivot.count.id},2)")
+
+.withName("marginPer").withFormula("=MINUS(DIVIDE_SCALE(${pivot.sum.charge},${pivot.count.id},2),DIVIDE_SCALE(${pivot.sum.cost},${pivot.count.id},2))")
+
+.withName("thisWeekMargin").withFormula("=SCALE(DIVIDE(${thisRow.profit},${pivot.sum.charge}),2)")
+
+.withName("previousWeekProfit").withFormula("=MINUS(${variancePivot.sum.charge},${variancePivot.sum.cost})")
+
+.withName("previousWeekMargin").withFormula("=SCALE(DIVIDE(${thisRow.previousWeekProfit},${variancePivot.sum.charge}),2)")
+
+.withName("marginThisVsPrevious").withFormula("=SCALE(MINUS(${thisRow.margin},${thisRow.marginPrevious}),3)")
+
+.withName("exception").withFormula("""
+   =IF(LT(${thisRow.margin},0),Negative Margin,IF(LT(${thisRow.marginThisVsPrevious},0),Margin Decreased,""))""")
+----
+
+* `displayFormat` *String*
+* `isVirtual` *Boolean, default false* - (needs reviewed - may only be required for report views using a data source with a *staticDataSupplier*)
+* `showPossibleValueLabel` *Boolean, default false* - To show a translated value for a Possible Value field (e.g., a name or other value meaningful to a user, instead of a foreign key).
+* `sourceFieldName` *String* - Used for the scenario where a possibleValue field is included in a report both as the foreign key (raw, id value), and the translated "label" value.
+In that case, the field marked with *showPossibleValueLabel* = true should be given a different name, and should use *sourceFieldName* to indicate the field that has the id value.
+** For example:
+
+[source,java]
+----
+// this field would have the "raw" warehouseId values
+// e.g., integers - foreign keys to a warehouse table.  Generally useful for machines to know.
+new QReportField("warehouseId")
+   .withLabel("Warehouse Id"),
+
+// this field would have the translated values from the warehouse PossibleValueSource
+// for example, maybe the name field from the warehouse table.  A string, useful for humans to read.
+new QReportField("warehouseName")
+   .withSourceFieldName("warehouseId")
+   .withShowPossibleValueLabel(true)
+   .withLabel("Warehouse Name"),
+----
+

docs/metaData/Tables.adoc

@@ -0,0 +1,49 @@
+== QQQ Tables
+include::../variables.adoc[]
+
+The core type of object in a QQQ Instance is the Table.
+In the most common use-case, a QQQ Table may be the in-app representation of a Database table.
+That is, it is a collection of records (or rows) of data, each of which has a set of fields (or columns).
+
+QQQ also allows other types of data sources ({link-backends}) to be used as tables, such as File systems, API's, Java enums or objects, etc.
+All of these backend types present the same interfaces (both user-interfaces, and application programming interfaces), regardless of their backend type.
+
+=== QTableMetaData
+Tables are defined in a QQQ Instance in a `*QTableMetaData*` object.
+All tables must reference a {link-backend}, a list of fields that define the shape of records in the table, and additional data to describe how to work with the table within its backend.
+
+*QTableMetaData Properties:*
+
+* `name` - *String, Required* - Unique name for the table within the QQQ Instance.
+* `label` - *String* - User-facing label for the table, presented in User Interfaces.
+Inferred from `name` if not set.
+* `backendName` - *String, Required* - Name of a {link-backend} in which this table's data is managed.
+* `fields` - *Map of String → {link-field}, Required* - The columns of data that make up all records in this table.
+* `primaryKeyField` - *String, Conditional* - Name of a {link-field} that serves as the primary key (e.g., unique identifier) for records in this table.
+* `uniqueKeys` - *List of UniqueKey* - Definition of additional unique constraints (from an RDBMS point of view) from the table.
+e.g., sets of columns which must have unique values for each record in the table.
+* `backendDetails` - *QTableBackendDetails or subclass* - Additional data to configure the table within its {link-backend}.
+* `automationDetails` - *QTableAutomationDetails* - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.
+* `customizers` - *Map of String → QCodeReference* - References to custom code that are injected into standard table actions, that allow applications to customize certain parts of how the table works.
+* `parentAppName` - *String* - Name of a {link-app} that this table exists within.
+* `icon` - *QIcon* - Icon associated with this table in certain user interfaces.
+* `recordLabelFormat` - *String* - Java Format String, used with `recordLabelFields` to produce a label shown for records from the table.
+* `recordLabelFields` - *List of String, Conditional* - Used with `recordLabelFormat` to provide values for any format specifiers in the format string.
+These strings must be field names within the table.
+** Example of using `recordLabelFormat` and `recordLabelFields`:
+
+[source,java]
+----
+// given these fields in the table:
+new QFieldMetaData("name", QFieldType.STRING)
+new QFieldMetaData("birthDate", QFieldType.DATE)
+
+// We can produce a record label such as "Darin Kelkhoff (1980-05-31)" via:
+.withRecordLabelFormat("%s (%s)")
+.withRecordLabelFields(List.of("name", "birthDate"))
+----
+* `sections` - *List of QFieldSection* - Mechanism to organize fields within user interfaces, into logical sections.
+If any sections are present in the table meta data, then all fields in the table must be listed in exactly 1 section.
+If no sections are defined, then instance enrichment will define default sections.
+* `associatedScripts` - *List of AssociatedScript* - Definition of user-defined scripts that can be associated with records within the table.
+* `enabledCapabilities` and `disabledCapabilities` - *Set of Capability enum values* - Overrides from the backend level, for capabilities that this table does or does not possess.

docs/metaData/Tables.html

@@ -0,0 +1,553 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 2.0.18">
+<title>QQQ Tables</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
+<style>
+/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
+/* Uncomment the following line when using as a custom stylesheet */
+/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
+html{font-family:sans-serif;-webkit-text-size-adjust:100%}
+a{background:none}
+a:focus{outline:thin dotted}
+a:active,a:hover{outline:0}
+h1{font-size:2em;margin:.67em 0}
+b,strong{font-weight:bold}
+abbr{font-size:.9em}
+abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
+dfn{font-style:italic}
+hr{height:0}
+mark{background:#ff0;color:#000}
+code,kbd,pre,samp{font-family:monospace;font-size:1em}
+pre{white-space:pre-wrap}
+q{quotes:"\201C" "\201D" "\2018" "\2019"}
+small{font-size:80%}
+sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
+sup{top:-.5em}
+sub{bottom:-.25em}
+img{border:0}
+svg:not(:root){overflow:hidden}
+figure{margin:0}
+audio,video{display:inline-block}
+audio:not([controls]){display:none;height:0}
+fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
+legend{border:0;padding:0}
+button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
+button,input{line-height:normal}
+button,select{text-transform:none}
+button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
+button[disabled],html input[disabled]{cursor:default}
+input[type=checkbox],input[type=radio]{padding:0}
+button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
+textarea{overflow:auto;vertical-align:top}
+table{border-collapse:collapse;border-spacing:0}
+*,::before,::after{box-sizing:border-box}
+html,body{font-size:100%}
+body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
+a:hover{cursor:pointer}
+img,object,embed{max-width:100%;height:auto}
+object,embed{height:100%}
+img{-ms-interpolation-mode:bicubic}
+.left{float:left!important}
+.right{float:right!important}
+.text-left{text-align:left!important}
+.text-right{text-align:right!important}
+.text-center{text-align:center!important}
+.text-justify{text-align:justify!important}
+.hide{display:none}
+img,object,svg{display:inline-block;vertical-align:middle}
+textarea{height:auto;min-height:50px}
+select{width:100%}
+.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
+div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
+a{color:#2156a5;text-decoration:underline;line-height:inherit}
+a:hover,a:focus{color:#1d4b8f}
+a img{border:0}
+p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
+p aside{font-size:.875em;line-height:1.35;font-style:italic}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
+h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
+h1{font-size:2.125em}
+h2{font-size:1.6875em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
+h4,h5{font-size:1.125em}
+h6{font-size:1em}
+hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
+em,i{font-style:italic;line-height:inherit}
+strong,b{font-weight:bold;line-height:inherit}
+small{font-size:60%;line-height:inherit}
+code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
+ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
+ul,ol{margin-left:1.5em}
+ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
+ul.circle{list-style-type:circle}
+ul.disc{list-style-type:disc}
+ul.square{list-style-type:square}
+ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
+ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
+dl dt{margin-bottom:.3125em;font-weight:bold}
+dl dd{margin-bottom:1.25em}
+blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
+blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
+@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
+h1{font-size:2.75em}
+h2{font-size:2.3125em}
+h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
+h4{font-size:1.4375em}}
+table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
+table thead,table tfoot{background:#f7f8f7}
+table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
+table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
+table tr.even,table tr.alt{background:#f8f8f7}
+table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
+h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
+h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
+.center{margin-left:auto;margin-right:auto}
+.stretch{width:100%}
+.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
+.clearfix::after,.float-group::after{clear:both}
+:not(pre).nobreak{word-wrap:normal}
+:not(pre).nowrap{white-space:nowrap}
+:not(pre).pre-wrap{white-space:pre-wrap}
+:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
+pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
+pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
+pre>code{display:block}
+pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
+em em{font-style:normal}
+strong strong{font-weight:400}
+.keyseq{color:rgba(51,51,51,.8)}
+kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
+.keyseq kbd:first-child{margin-left:0}
+.keyseq kbd:last-child{margin-right:0}
+.menuseq,.menuref{color:#000}
+.menuseq b:not(.caret),.menuref{font-weight:inherit}
+.menuseq{word-spacing:-.02em}
+.menuseq b.caret{font-size:1.25em;line-height:.8}
+.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
+b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
+b.button::before{content:"[";padding:0 3px 0 2px}
+b.button::after{content:"]";padding:0 2px 0 3px}
+p a>code:hover{color:rgba(0,0,0,.9)}
+#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
+#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
+#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
+#content{margin-top:1.25em}
+#content::before{content:none}
+#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
+#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
+#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
+#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
+#header .details span:first-child{margin-left:-.125em}
+#header .details span.email a{color:rgba(0,0,0,.85)}
+#header .details br{display:none}
+#header .details br+span::before{content:"\00a0\2013\00a0"}
+#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
+#header .details br+span#revremark::before{content:"\00a0|\00a0"}
+#header #revnumber{text-transform:capitalize}
+#header #revnumber::after{content:"\00a0"}
+#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
+#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
+#toc>ul{margin-left:.125em}
+#toc ul.sectlevel0>li>a{font-style:italic}
+#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
+#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
+#toc li{line-height:1.3334;margin-top:.3334em}
+#toc a{text-decoration:none}
+#toc a:active{text-decoration:underline}
+#toctitle{color:#7a2518;font-size:1.2em}
+@media screen and (min-width:768px){#toctitle{font-size:1.375em}
+body.toc2{padding-left:15em;padding-right:0}
+#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
+#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
+#toc.toc2>ul{font-size:.9em;margin-bottom:0}
+#toc.toc2 ul ul{margin-left:0;padding-left:1em}
+#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
+body.toc2.toc-right{padding-left:0;padding-right:15em}
+body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
+@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
+#toc.toc2{width:20em}
+#toc.toc2 #toctitle{font-size:1.375em}
+#toc.toc2>ul{font-size:.95em}
+#toc.toc2 ul ul{padding-left:1.25em}
+body.toc2.toc-right{padding-left:0;padding-right:20em}}
+#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
+#content #toc>:first-child{margin-top:0}
+#content #toc>:last-child{margin-bottom:0}
+#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
+#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
+#content{margin-bottom:.625em}
+.sect1{padding-bottom:.625em}
+@media screen and (min-width:768px){#content{margin-bottom:1.25em}
+.sect1{padding-bottom:1.25em}}
+.sect1:last-child{padding-bottom:0}
+.sect1+.sect1{border-top:1px solid #e7e7e9}
+#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
+#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
+#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
+#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
+#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
+details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
+details{margin-left:1.25rem}
+details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
+details>summary::-webkit-details-marker{display:none}
+details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
+details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
+details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
+.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
+table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
+.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
+.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
+.admonitionblock>table td.icon{text-align:center;width:80px}
+.admonitionblock>table td.icon img{max-width:none}
+.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
+.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
+.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
+.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
+.exampleblock>.content>:first-child{margin-top:0}
+.exampleblock>.content>:last-child{margin-bottom:0}
+.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
+.sidebarblock>:first-child{margin-top:0}
+.sidebarblock>:last-child{margin-bottom:0}
+.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
+.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
+.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
+@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
+@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
+.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
+.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
+.listingblock>.content{position:relative}
+.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
+.listingblock:hover code[data-lang]::before{display:block}
+.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
+.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
+.listingblock pre.highlightjs{padding:0}
+.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
+.listingblock pre.prettyprint{border-width:0}
+.prettyprint{background:#f7f7f8}
+pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
+pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
+pre.prettyprint li code[data-lang]::before{opacity:1}
+pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
+table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
+table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
+table.linenotable td.code{padding-left:.75em}
+table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
+pre.pygments span.linenos{display:inline-block;margin-right:.75em}
+.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
+.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
+.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
+.quoteblock blockquote{margin:0;padding:0;border:0}
+.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
+.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
+.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
+.verseblock{margin:0 1em 1.25em}
+.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
+.verseblock pre strong{font-weight:400}
+.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
+.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
+.quoteblock .attribution br,.verseblock .attribution br{display:none}
+.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
+.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
+.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
+.quoteblock.abstract{margin:0 1em 1.25em;display:block}
+.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
+.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
+.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
+.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
+.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
+p.tableblock:last-child{margin-bottom:0}
+td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
+td.tableblock>.content>:last-child{margin-bottom:-1.25em}
+table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
+table.grid-all>*>tr>*{border-width:1px}
+table.grid-cols>*>tr>*{border-width:0 1px}
+table.grid-rows>*>tr>*{border-width:1px 0}
+table.frame-all{border-width:1px}
+table.frame-ends{border-width:1px 0}
+table.frame-sides{border-width:0 1px}
+table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
+table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
+table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
+table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
+table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
+th.halign-left,td.halign-left{text-align:left}
+th.halign-right,td.halign-right{text-align:right}
+th.halign-center,td.halign-center{text-align:center}
+th.valign-top,td.valign-top{vertical-align:top}
+th.valign-bottom,td.valign-bottom{vertical-align:bottom}
+th.valign-middle,td.valign-middle{vertical-align:middle}
+table thead th,table tfoot th{font-weight:bold}
+tbody tr th{background:#f7f8f7}
+tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
+p.tableblock>code:only-child{background:none;padding:0}
+p.tableblock{font-size:1em}
+ol{margin-left:1.75em}
+ul li ol{margin-left:1.5em}
+dl dd{margin-left:1.125em}
+dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
+li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
+ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
+ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
+ul.unstyled,ol.unstyled{margin-left:0}
+li>p:empty:only-child::before{content:"";display:inline-block}
+ul.checklist>li>p:first-child{margin-left:-1em}
+ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
+ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
+ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
+ul.inline>li{margin-left:1.25em}
+.unstyled dl dt{font-weight:400;font-style:normal}
+ol.arabic{list-style-type:decimal}
+ol.decimal{list-style-type:decimal-leading-zero}
+ol.loweralpha{list-style-type:lower-alpha}
+ol.upperalpha{list-style-type:upper-alpha}
+ol.lowerroman{list-style-type:lower-roman}
+ol.upperroman{list-style-type:upper-roman}
+ol.lowergreek{list-style-type:lower-greek}
+.hdlist>table,.colist>table{border:0;background:none}
+.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
+td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
+td.hdlist1{font-weight:bold;padding-bottom:1.25em}
+td.hdlist2{word-wrap:anywhere}
+.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
+.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
+.colist td:not([class]):first-child img{max-width:none}
+.colist td:not([class]):last-child{padding:.25em 0}
+.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
+.imageblock.left{margin:.25em .625em 1.25em 0}
+.imageblock.right{margin:.25em 0 1.25em .625em}
+.imageblock>.title{margin-bottom:0}
+.imageblock.thumb,.imageblock.th{border-width:6px}
+.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
+.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
+.image.left{margin-right:.625em}
+.image.right{margin-left:.625em}
+a.image{text-decoration:none;display:inline-block}
+a.image object{pointer-events:none}
+sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
+sup.footnote a,sup.footnoteref a{text-decoration:none}
+sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
+#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
+#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
+#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
+#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
+#footnotes .footnote:last-of-type{margin-bottom:0}
+#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
+div.unbreakable{page-break-inside:avoid}
+.big{font-size:larger}
+.small{font-size:smaller}
+.underline{text-decoration:underline}
+.overline{text-decoration:overline}
+.line-through{text-decoration:line-through}
+.aqua{color:#00bfbf}
+.aqua-background{background:#00fafa}
+.black{color:#000}
+.black-background{background:#000}
+.blue{color:#0000bf}
+.blue-background{background:#0000fa}
+.fuchsia{color:#bf00bf}
+.fuchsia-background{background:#fa00fa}
+.gray{color:#606060}
+.gray-background{background:#7d7d7d}
+.green{color:#006000}
+.green-background{background:#007d00}
+.lime{color:#00bf00}
+.lime-background{background:#00fa00}
+.maroon{color:#600000}
+.maroon-background{background:#7d0000}
+.navy{color:#000060}
+.navy-background{background:#00007d}
+.olive{color:#606000}
+.olive-background{background:#7d7d00}
+.purple{color:#600060}
+.purple-background{background:#7d007d}
+.red{color:#bf0000}
+.red-background{background:#fa0000}
+.silver{color:#909090}
+.silver-background{background:#bcbcbc}
+.teal{color:#006060}
+.teal-background{background:#007d7d}
+.white{color:#bfbfbf}
+.white-background{background:#fafafa}
+.yellow{color:#bfbf00}
+.yellow-background{background:#fafa00}
+span.icon>.fa{cursor:default}
+a span.icon>.fa{cursor:inherit}
+.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
+.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
+.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
+.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
+.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
+.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
+.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
+.conum[data-value] *{color:#fff!important}
+.conum[data-value]+b{display:none}
+.conum[data-value]::after{content:attr(data-value)}
+pre .conum[data-value]{position:relative;top:-.125em}
+b.conum *{color:inherit!important}
+.conum:not([data-value]):empty{display:none}
+dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
+h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
+p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
+p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem}
+p{margin-bottom:1.25rem}
+.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
+.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
+.print-only{display:none!important}
+@page{margin:1.25cm .75cm}
+@media print{*{box-shadow:none!important;text-shadow:none!important}
+html{font-size:80%}
+a{color:inherit!important;text-decoration:underline!important}
+a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
+a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
+abbr[title]{border-bottom:1px dotted}
+abbr[title]::after{content:" (" attr(title) ")"}
+pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
+thead{display:table-header-group}
+svg{max-width:100%}
+p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
+h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
+#header,#content,#footnotes,#footer{max-width:none}
+#toc,.sidebarblock,.exampleblock>.content{background:none!important}
+#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
+body.book #header{text-align:center}
+body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
+body.book #header .details{border:0!important;display:block;padding:0!important}
+body.book #header .details span:first-child{margin-left:0!important}
+body.book #header .details br{display:block}
+body.book #header .details br+span::before{content:none!important}
+body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
+body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
+.listingblock code[data-lang]::before{display:block}
+#footer{padding:0 .9375em}
+.hide-on-print{display:none!important}
+.print-only{display:block!important}
+.hide-for-print{display:none!important}
+.show-for-print{display:inherit!important}}
+@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
+.sect1{padding:0!important}
+.sect1+.sect1{border:0}
+#footer{background:none}
+#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
+@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
+</style>
+</head>
+<body class="article">
+<div id="header">
+</div>
+<div id="content">
+<div class="sect1">
+<h2 id="_qqq_tables">QQQ Tables</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The core type of object in a QQQ Instance is the Table.
+In the most common use-case, a QQQ Table may be the in-app representation of a Database table.
+That is, it is a collection of records (or rows) of data, each of which has a set of fields (or columns).</p>
+</div>
+<div class="paragraph">
+<p>QQQ also allows other types of data sources (<a href="Backends{relfilesuffix}">QQQ Backends</a>) to be used as tables, such as File systems, API&#8217;s, Java enums or objects, etc.
+All of these backend types present the same interfaces (both user-interfaces, and application programming interfaces), regardless of their backend type.</p>
+</div>
+<div class="sect2">
+<h3 id="_qtablemetadata">QTableMetaData</h3>
+<div class="paragraph">
+<p>Tables are defined in a QQQ Instance in a <code><strong>QTableMetaData</strong></code> object.
+All tables must reference a <a href="Backends{relfilesuffix}">QQQ Backend</a>, a list of fields that define the shape of records in the table, and additional data to describe how to work with the table within its backend.</p>
+</div>
+<div class="paragraph">
+<p><strong>QTableMetaData Properties:</strong></p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>name</code> - <strong>String, Required</strong> - Unique name for the table within the QQQ Instance.</p>
+</li>
+<li>
+<p><code>label</code> - <strong>String</strong> - User-facing label for the table, presented in User Interfaces.
+Inferred from <code>name</code> if not set.</p>
+</li>
+<li>
+<p><code>backendName</code> - <strong>String, Required</strong> - Name of a <a href="Backends{relfilesuffix}">QQQ Backend</a> in which this table&#8217;s data is managed.</p>
+</li>
+<li>
+<p><code>fields</code> - <strong>Map of String → <a href="Fields{relfilesuffix}">QQQ Field</a>, Required</strong> - The columns of data that make up all records in this table.</p>
+</li>
+<li>
+<p><code>primaryKeyField</code> - <strong>String, Conditional</strong> - Name of a <a href="Fields{relfilesuffix}">QQQ Field</a> that serves as the primary key (e.g., unique identifier) for records in this table.</p>
+</li>
+<li>
+<p><code>uniqueKeys</code> - <strong>List of UniqueKey</strong> - Definition of additional unique constraints (from an RDBMS point of view) from the table.
+e.g., sets of columns which must have unique values for each record in the table.</p>
+</li>
+<li>
+<p><code>backendDetails</code> - <strong>QTableBackendDetails or subclass</strong> - Additional data to configure the table within its <a href="Backends{relfilesuffix}">QQQ Backend</a>.</p>
+</li>
+<li>
+<p><code>automationDetails</code> - <strong>QTableAutomationDetails</strong> - Configuration of automated jobs that run against records in the table, e.g., upon insert or update.</p>
+</li>
+<li>
+<p><code>customizers</code> - <strong>Map of String → QCodeReference</strong> - References to custom code that are injected into standard table actions, that allow applications to customize certain parts of how the table works.</p>
+</li>
+<li>
+<p><code>parentAppName</code> - <strong>String</strong> - Name of a <a href="Apps{relfilesuffix}">QQQ App</a> that this table exists within.</p>
+</li>
+<li>
+<p><code>icon</code> - <strong>QIcon</strong> - Icon associated with this table in certain user interfaces.</p>
+</li>
+<li>
+<p><code>recordLabelFormat</code> - <strong>String</strong> - Java Format String, used with <code>recordLabelFields</code> to produce a label shown for records from the table.</p>
+</li>
+<li>
+<p><code>recordLabelFields</code> - <strong>List of String, Conditional</strong> - Used with <code>recordLabelFormat</code> to provide values for any format specifiers in the format string.
+These strings must be field names within the table.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>Example of using <code>recordLabelFormat</code> and <code>recordLabelFields</code>:</p>
+</li>
+</ul>
+</div>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span style="color:#777">// given these fields in the table:</span>
+<span style="color:#080;font-weight:bold">new</span> QFieldMetaData(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">name</span><span style="color:#710">&quot;</span></span>, QFieldType.STRING)
+<span style="color:#080;font-weight:bold">new</span> QFieldMetaData(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">birthDate</span><span style="color:#710">&quot;</span></span>, QFieldType.DATE)
+
+<span style="color:#777">// We can produce a record label such as &quot;Darin Kelkhoff (1980-05-31)&quot; via:</span>
+.withRecordLabelFormat(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">%s (%s)</span><span style="color:#710">&quot;</span></span>)
+.withRecordLabelFields(<span style="color:#0a8;font-weight:bold">List</span>.of(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">name</span><span style="color:#710">&quot;</span></span>, <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">&quot;</span><span style="color:#D20">birthDate</span><span style="color:#710">&quot;</span></span>))</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>sections</code> - <strong>List of QFieldSection</strong> - Mechanism to organize fields within user interfaces, into logical sections.
+If any sections are present in the table meta data, then all fields in the table must be listed in exactly 1 section.
+If no sections are defined, then instance enrichment will define default sections.</p>
+</li>
+<li>
+<p><code>associatedScripts</code> - <strong>List of AssociatedScript</strong> - Definition of user-defined scripts that can be associated with records within the table.</p>
+</li>
+<li>
+<p><code>enabledCapabilities</code> and <code>disabledCapabilities</code> - <strong>Set of Capability enum values</strong> - Overrides from the backend level, for capabilities that this table does or does not possess.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2022-11-21 09:02:56 -0600
+</div>
+</div>
+</body>
+</html>

docs/variables.adoc

@@ -0,0 +1,13 @@
+ifdef::env-name[:relfilesuffix: .adoc]
+:link-backend: link:Backends{relfilesuffix}[QQQ Backend]
+:link-backends: link:Backends{relfilesuffix}[QQQ Backends]
+:link-table: link:Tables{relfilesuffix}[QQQ Table]
+:link-tables: link:Tables{relfilesuffix}[QQQ Tables]
+:link-join: link:Joins{relfilesuffix}[QQQ Join]
+:link-joins: link:Joins{relfilesuffix}[QQQ Joins]
+:link-field: link:Fields{relfilesuffix}[QQQ Field]
+:link-fields: link:Fields{relfilesuffix}[QQQ Fields]
+:link-process: link:Processes{relfilesuffix}[QQQ Process]
+:link-processes: link:Processes{relfilesuffix}[QQQ Processes]
+:link-app: link:Apps{relfilesuffix}[QQQ App]
+:link-apps: link:Apps{relfilesuffix}[QQQ Apps]

pom.xml

@@ -37,12 +37,14 @@
       <module>qqq-middleware-picocli</module>
       <module>qqq-middleware-javalin</module>
       <module>qqq-middleware-lambda</module>
+      <module>qqq-middleware-slack</module>
+      <module>qqq-middleware-api</module>
       <module>qqq-utility-lambdas</module>
       <module>qqq-sample-project</module>
    </modules>
 
    <properties>
-      <revision>0.8.0</revision>
+      <revision>0.20.0-SNAPSHOT</revision>
 
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
@@ -204,6 +206,63 @@
                <skipUpdateVersion>true</skipUpdateVersion>
             </configuration>
          </plugin>
+         <plugin>
+            <artifactId>exec-maven-plugin</artifactId>
+            <groupId>org.codehaus.mojo</groupId>
+            <version>3.0.0</version>
+            <executions>
+               <execution>
+                  <id>test-coverage-summary</id>
+                  <phase>verify</phase>
+                  <goals>
+                     <goal>exec</goal>
+                  </goals>
+                  <configuration>
+                     <executable>sh</executable>
+                     <arguments>
+                        <argument>-c</argument>
+                        <argument>
+                           <![CDATA[
+if [ ! -e target/site/jacoco/index.html ]; then
+   echo "No jacoco coverage report here.";
+   exit;
+fi
+
+echo
+echo "Jacoco coverage summary report:"
+echo "   See also target/site/jacoco/index.html"
+echo "   and https://www.jacoco.org/jacoco/trunk/doc/counters.html"
+echo "------------------------------------------------------------"
+
+which xpath > /dev/null 2>&1
+if [ "$?" == "0" ]; then
+   echo "Element\nInstructions Missed\nInstruction Coverage\nBranches Missed\nBranch Coverage\nComplexity Missed\nComplexity Hit\nLines Missed\nLines Hit\nMethods Missed\nMethods Hit\nClasses Missed\nClasses Hit\n" > /tmp/$$.headers
+   xpath -n -q -e '/html/body/table/tfoot/tr[1]/td/text()' target/site/jacoco/index.html > /tmp/$$.values
+   paste /tmp/$$.headers /tmp/$$.values | tail +2 | awk -v FS='\t' '{printf("%-20s %s\n",$1,$2)}'
+   rm /tmp/$$.headers /tmp/$$.values
+else
+   echo "xpath is not installed.  Jacoco coverage summary will not be produced here...";
+fi
+
+which xpath > /dev/null 2>&1
+if [ "$?" == "0" ]; then
+   echo "Untested classes, per Jacoco:"
+   echo "-----------------------------"
+   for i in target/site/jacoco/*/index.html; do
+      html2text -width 500 -nobs $i | sed '1,/^Total/d;' | grep -v Created | sed 's/ \+/ /g' | sed 's/ [[:digit:]]$//' | grep -v 0$ | cut -d' ' -f1;
+   done;
+   echo
+else
+   echo "html2text is not installed.  Untested classes from Jacoco will not be printed here...";
+fi
+
+                           ]]>
+                        </argument>
+                     </arguments>
+                  </configuration>
+               </execution>
+            </executions>
+         </plugin>
          <plugin>
             <groupId>org.jacoco</groupId>
             <artifactId>jacoco-maven-plugin</artifactId>
@@ -247,56 +306,14 @@
                </execution>
                <execution>
                   <id>post-unit-test</id>
-                  <phase>verify</phase>
+                  <!-- <phase>verify</phase> -->
+                  <phase>post-integration-test</phase>
                   <goals>
                      <goal>report</goal>
                   </goals>
                </execution>
             </executions>
          </plugin>
-         <plugin>
-            <artifactId>exec-maven-plugin</artifactId>
-            <groupId>org.codehaus.mojo</groupId>
-            <version>3.0.0</version>
-            <executions>
-               <execution>
-                  <id>test-coverage-summary</id>
-                  <phase>verify</phase>
-                  <goals>
-                     <goal>exec</goal>
-                  </goals>
-                  <configuration>
-                     <executable>sh</executable>
-                     <arguments>
-                        <argument>-c</argument>
-                        <argument>
-                           <![CDATA[
-if [ ! -e target/site/jacoco/index.html ]; then
-   echo "No jacoco coverage report here.";
-   exit;
-fi
-
-echo
-echo "Jacoco coverage summary report:"
-echo "   See also target/site/jacoco/index.html"
-echo "   and https://www.jacoco.org/jacoco/trunk/doc/counters.html"
-echo "------------------------------------------------------------"
-which xpath > /dev/null 2>&1
-if [ "$?" == "0" ]; then
-   echo "Element\nInstructions Missed\nInstruction Coverage\nBranches Missed\nBranch Coverage\nComplexity Missed\nComplexity Hit\nLines Missed\nLines Hit\nMethods Missed\nMethods Hit\nClasses Missed\nClasses Hit\n" > /tmp/$$.headers
-   xpath -n -q -e '/html/body/table/tfoot/tr[1]/td/text()' target/site/jacoco/index.html > /tmp/$$.values
-   paste /tmp/$$.headers /tmp/$$.values | tail +2 | awk -v FS='\t' '{printf("%-20s %s\n",$1,$2)}'
-   rm /tmp/$$.headers /tmp/$$.values
-else
-   echo "xpath is not installed.  Jacoco coverage summary will not be produced here..";
-fi
-                           ]]>
-                        </argument>
-                     </arguments>
-                  </configuration>
-               </execution>
-            </executions>
-         </plugin>
       </plugins>
    </build>
 

qqq-backend-core/pom.xml

@@ -56,20 +56,35 @@
          <groupId>software.amazon.awssdk</groupId>
          <artifactId>quicksight</artifactId>
       </dependency>
+      <dependency>
+         <groupId>software.amazon.awssdk</groupId>
+         <artifactId>apigateway</artifactId>
+      </dependency>
+      <dependency>
+         <groupId>com.amazonaws</groupId>
+         <artifactId>aws-java-sdk-secretsmanager</artifactId>
+         <version>1.12.385</version>
+      </dependency>
+
       <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-databind</artifactId>
-         <version>2.14.0-rc1</version>
+         <version>2.14.0</version>
       </dependency>
       <dependency>
          <groupId>com.fasterxml.jackson.datatype</groupId>
          <artifactId>jackson-datatype-jsr310</artifactId>
-         <version>2.13.0</version>
+         <version>2.14.0</version>
+      </dependency>
+      <dependency>
+         <groupId>com.fasterxml.jackson.dataformat</groupId>
+         <artifactId>jackson-dataformat-yaml</artifactId>
+         <version>2.14.0</version>
       </dependency>
       <dependency>
          <groupId>org.json</groupId>
          <artifactId>json</artifactId>
-         <version>20210307</version>
+         <version>20231013</version>
       </dependency>
       <dependency>
          <groupId>org.apache.commons</groupId>
@@ -89,8 +104,18 @@
       </dependency>
       <dependency>
          <groupId>com.auth0</groupId>
-         <artifactId>mvc-auth-commons</artifactId>
-         <version>1.9.2</version>
+         <artifactId>auth0</artifactId>
+         <version>2.1.0</version>
+      </dependency>
+      <dependency>
+         <groupId>com.auth0</groupId>
+         <artifactId>java-jwt</artifactId>
+         <version>4.4.0</version>
+      </dependency>
+      <dependency>
+         <groupId>com.auth0</groupId>
+         <artifactId>jwks-rsa</artifactId>
+         <version>0.22.0</version>
       </dependency>
       <dependency>
          <groupId>io.github.cdimascio</groupId>
@@ -167,6 +192,13 @@
          <scope>test</scope>
       </dependency>
 
+      <dependency>
+         <groupId>org.mockito</groupId>
+         <artifactId>mockito-core</artifactId>
+         <version>4.8.1</version>
+         <scope>test</scope>
+      </dependency>
+
    </dependencies>
 
    <build>

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

@@ -23,8 +23,9 @@ package com.kingsrook.qqq.backend.core.actions;
 
 
 import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.Executors;
 import java.util.concurrent.Future;
+import com.kingsrook.qqq.backend.core.context.CapturedContext;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionOutput;
@@ -50,11 +51,13 @@ public abstract class AbstractQActionBiConsumer<I extends AbstractActionInput, O
     *******************************************************************************/
    public Future<Void> executeAsync(I input, O output)
    {
+      CapturedContext         capturedContext   = QContext.capture();
       CompletableFuture<Void> completableFuture = new CompletableFuture<>();
-      Executors.newCachedThreadPool().submit(() ->
+      ActionHelper.getExecutorService().submit(() ->
       {
          try
          {
+            QContext.init(capturedContext);
             execute(input, output);
             completableFuture.complete(null);
          }
@@ -62,6 +65,10 @@ public abstract class AbstractQActionBiConsumer<I extends AbstractActionInput, O
          {
             completableFuture.completeExceptionally(e);
          }
+         finally
+         {
+            QContext.clear();
+         }
       });
       return (completableFuture);
    }

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

@@ -23,8 +23,9 @@ package com.kingsrook.qqq.backend.core.actions;
 
 
 import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.Executors;
 import java.util.concurrent.Future;
+import com.kingsrook.qqq.backend.core.context.CapturedContext;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionOutput;
@@ -50,11 +51,13 @@ public abstract class AbstractQActionFunction<I extends AbstractActionInput, O e
     *******************************************************************************/
    public Future<O> executeAsync(I input)
    {
+      CapturedContext      capturedContext   = QContext.capture();
       CompletableFuture<O> completableFuture = new CompletableFuture<>();
-      Executors.newCachedThreadPool().submit(() ->
+      ActionHelper.getExecutorService().submit(() ->
       {
          try
          {
+            QContext.init(capturedContext);
             O output = execute(input);
             completableFuture.complete(output);
          }
@@ -62,6 +65,10 @@ public abstract class AbstractQActionFunction<I extends AbstractActionInput, O e
          {
             completableFuture.completeExceptionally(e);
          }
+         finally
+         {
+            QContext.clear();
+         }
       });
       return (completableFuture);
    }

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

@@ -24,10 +24,17 @@ package com.kingsrook.qqq.backend.core.actions;
 
 import java.io.Serializable;
 import java.util.List;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.SynchronousQueue;
+import java.util.concurrent.ThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Function;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleDispatcher;
 import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleInterface;
 
@@ -37,15 +44,42 @@ import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModu
  *******************************************************************************/
 public class ActionHelper
 {
+   /////////////////////////////////////////////////////////////////////////////
+   // we would probably use Executors.newCachedThreadPool() - but - it has no //
+   // maxPoolSize...  we think some limit is good, so that at a large number  //
+   // of attempted concurrent jobs we'll have new jobs block, rather than     //
+   // exhausting all server resources and locking up "everything"             //
+   // also, it seems like keeping a handful of core-threads around is very    //
+   // little actual waste, and better than ever wasting time starting a new   //
+   // one, which we know we'll often be doing.                                //
+   /////////////////////////////////////////////////////////////////////////////
+   private static Integer         CORE_THREADS    = 8;
+   private static Integer         MAX_THREADS     = 500;
+   private static ExecutorService executorService = new ThreadPoolExecutor(CORE_THREADS, MAX_THREADS, 60L, TimeUnit.SECONDS, new SynchronousQueue<>());
+
+
 
    /*******************************************************************************
     **
     *******************************************************************************/
    public static void validateSession(AbstractActionInput request) throws QException
    {
+      QInstance qInstance = QContext.getQInstance();
+      QSession  qSession  = QContext.getQSession();
+
+      if(qInstance == null)
+      {
+         throw (new QException("QInstance was not set in QContext."));
+      }
+
+      if(qSession == null)
+      {
+         throw (new QException("QSession was not set in QContext."));
+      }
+
       QAuthenticationModuleDispatcher qAuthenticationModuleDispatcher = new QAuthenticationModuleDispatcher();
-      QAuthenticationModuleInterface  authenticationModule            = qAuthenticationModuleDispatcher.getQModule(request.getAuthenticationMetaData());
-      if(!authenticationModule.isSessionValid(request.getInstance(), request.getSession()))
+      QAuthenticationModuleInterface  authenticationModule            = qAuthenticationModuleDispatcher.getQModule(qInstance.getAuthentication());
+      if(!authenticationModule.isSessionValid(qInstance, qSession))
       {
          throw new QAuthenticationException("Invalid session in request");
       }
@@ -53,6 +87,17 @@ public class ActionHelper
 
 
 
+   /*******************************************************************************
+    ** access an executor service for sharing among the executeAsync methods of all
+    ** actions.
+    *******************************************************************************/
+   static ExecutorService getExecutorService()
+   {
+      return (executorService);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/async/AsyncJobCallback.java

@@ -95,6 +95,23 @@ public class AsyncJobCallback
 
 
 
+   /*******************************************************************************
+    ** Update the current and total fields, but ONLY if the new values are
+    ** both >= the previous values.
+    *******************************************************************************/
+   public void updateStatusOnlyUpwards(int current, int total)
+   {
+      boolean currentIsOkay = (this.asyncJobStatus.getCurrent() == null || this.asyncJobStatus.getCurrent() <= current);
+      boolean totalIsOkay   = (this.asyncJobStatus.getTotal() == null || this.asyncJobStatus.getTotal() <= total);
+
+      if(currentIsOkay && totalIsOkay)
+      {
+         updateStatus(current, total);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Increase the 'current' value in the '1 of 2' sense.
     *******************************************************************************/

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/async/AsyncJobManager.java

@@ -28,15 +28,23 @@ import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.SynchronousQueue;
+import java.util.concurrent.ThreadPoolExecutor;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
+import com.kingsrook.qqq.backend.core.context.CapturedContext;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.state.InMemoryStateProvider;
 import com.kingsrook.qqq.backend.core.state.StateProviderInterface;
 import com.kingsrook.qqq.backend.core.state.StateType;
 import com.kingsrook.qqq.backend.core.state.UUIDAndTypeStateKey;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import org.apache.logging.log4j.Level;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -44,7 +52,23 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class AsyncJobManager
 {
-   private static final Logger LOG = LogManager.getLogger(AsyncJobManager.class);
+   private static final QLogger LOG = QLogger.getLogger(AsyncJobManager.class);
+
+   /////////////////////////////////////////////////////////////////////////////
+   // we would probably use Executors.newCachedThreadPool() - but - it has no //
+   // maxPoolSize...  we think some limit is good, so that at a large number  //
+   // of attempted concurrent jobs we'll have new jobs block, rather than     //
+   // exhausting all server resources and locking up "everything"             //
+   // also, it seems like keeping a handful of core-threads around is very    //
+   // little actual waste, and better than ever wasting time starting a new   //
+   // one, which we know we'll often be doing.                                //
+   /////////////////////////////////////////////////////////////////////////////
+   private static Integer         CORE_THREADS    = 8;
+   private static Integer         MAX_THREADS     = 500;
+   private static ExecutorService executorService = new ThreadPoolExecutor(CORE_THREADS, MAX_THREADS, 60L, TimeUnit.SECONDS, new SynchronousQueue<>());
+
+
+   private String forcedJobUUID = null;
 
 
 
@@ -65,17 +89,20 @@ public class AsyncJobManager
     *******************************************************************************/
    public <T extends Serializable> T startJob(String jobName, long timeout, TimeUnit timeUnit, AsyncJob<T> asyncJob) throws JobGoingAsyncException, QException
    {
-      UUIDAndTypeStateKey uuidAndTypeStateKey = new UUIDAndTypeStateKey(UUID.randomUUID(), StateType.ASYNC_JOB_STATUS);
+      UUID                jobUUID             = StringUtils.hasContent(forcedJobUUID) ? UUID.fromString(forcedJobUUID) : UUID.randomUUID();
+      UUIDAndTypeStateKey uuidAndTypeStateKey = new UUIDAndTypeStateKey(jobUUID, StateType.ASYNC_JOB_STATUS);
       AsyncJobStatus      asyncJobStatus      = new AsyncJobStatus();
       asyncJobStatus.setState(AsyncJobState.RUNNING);
       getStateProvider().put(uuidAndTypeStateKey, asyncJobStatus);
 
       try
       {
+         CapturedContext capturedContext = QContext.capture();
          CompletableFuture<T> future = CompletableFuture.supplyAsync(() ->
          {
+            QContext.init(capturedContext);
             return (runAsyncJob(jobName, asyncJob, uuidAndTypeStateKey, asyncJobStatus));
-         });
+         }, executorService);
 
          if(timeout == 0)
          {
@@ -147,12 +174,17 @@ public class AsyncJobManager
          asyncJobStatus.setState(AsyncJobState.ERROR);
          asyncJobStatus.setCaughtException(e);
          getStateProvider().put(uuidAndTypeStateKey, asyncJobStatus);
-         LOG.warn("Job " + uuidAndTypeStateKey.getUuid() + " ended with an exception: ", e);
+
+         //////////////////////////////////////////////////////
+         // if user facing, just log an info, warn otherwise //
+         //////////////////////////////////////////////////////
+         LOG.log((e instanceof QUserFacingException) ? Level.INFO : Level.WARN, "Job ended with an exception", e, logPair("jobId", uuidAndTypeStateKey.getUuid()));
          throw (new CompletionException(e));
       }
       finally
       {
          Thread.currentThread().setName(originalThreadName);
+         QContext.clear();
       }
    }
 
@@ -194,4 +226,35 @@ public class AsyncJobManager
       jobStatus.ifPresent(asyncJobStatus -> asyncJobStatus.setCancelRequested(true));
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for forcedJobUUID
+    *******************************************************************************/
+   public String getForcedJobUUID()
+   {
+      return (this.forcedJobUUID);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for forcedJobUUID
+    *******************************************************************************/
+   public void setForcedJobUUID(String forcedJobUUID)
+   {
+      this.forcedJobUUID = forcedJobUUID;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for forcedJobUUID
+    *******************************************************************************/
+   public AsyncJobManager withForcedJobUUID(String forcedJobUUID)
+   {
+      this.forcedJobUUID = forcedJobUUID;
+      return (this);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/async/AsyncRecordPipeLoop.java

@@ -25,11 +25,13 @@ package com.kingsrook.qqq.backend.core.actions.async;
 import java.io.Serializable;
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
+import com.kingsrook.qqq.backend.core.actions.reporting.BufferedRecordPipe;
 import com.kingsrook.qqq.backend.core.actions.reporting.RecordPipe;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.utils.SleepUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import com.kingsrook.qqq.backend.core.utils.lambdas.UnsafeFunction;
+import com.kingsrook.qqq.backend.core.utils.lambdas.UnsafeSupplier;
 
 
 /*******************************************************************************
@@ -40,13 +42,14 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class AsyncRecordPipeLoop
 {
-   private static final Logger LOG = LogManager.getLogger(AsyncRecordPipeLoop.class);
+   private static final QLogger LOG = QLogger.getLogger(AsyncRecordPipeLoop.class);
 
    private static final int TIMEOUT_AFTER_NO_RECORDS_MS = 10 * 60 * 1000;
 
-   private static final int MAX_SLEEP_MS           = 1000;
-   private static final int INIT_SLEEP_MS          = 10;
-   private static final int MIN_RECORDS_TO_CONSUME = 10;
+   private static final int MAX_SLEEP_MS  = 1000;
+   private static final int INIT_SLEEP_MS = 10;
+
+   private Integer minRecordsToConsume = 10;
 
 
 
@@ -62,7 +65,7 @@ public class AsyncRecordPipeLoop
     ** @param consumer lambda that consumes records from the pipe
     *                  e.g., a transform/load step.
     *******************************************************************************/
-   public int run(String jobName, Integer recordLimit, RecordPipe recordPipe, UnsafeFunction<AsyncJobCallback, ? extends Serializable> supplier, UnsafeSupplier<Integer> consumer) throws QException
+   public int run(String jobName, Integer recordLimit, RecordPipe recordPipe, UnsafeFunction<AsyncJobCallback, ? extends Serializable, QException> supplier, UnsafeSupplier<Integer, QException> consumer) throws QException
    {
       ///////////////////////////////////////////////////
       // start the extraction function as an async job //
@@ -82,7 +85,7 @@ public class AsyncRecordPipeLoop
 
       while(jobState.equals(AsyncJobState.RUNNING))
       {
-         if(recordPipe.countAvailableRecords() < MIN_RECORDS_TO_CONSUME)
+         if(recordPipe.countAvailableRecords() < minRecordsToConsume)
          {
             ///////////////////////////////////////////////////////////////
             // if the pipe is too empty, sleep to let the producer work. //
@@ -140,6 +143,11 @@ public class AsyncRecordPipeLoop
          jobState = asyncJobStatus.getState();
       }
 
+      if(recordPipe instanceof BufferedRecordPipe bufferedRecordPipe)
+      {
+         bufferedRecordPipe.finalFlush();
+      }
+
       LOG.debug("Job [" + jobUUID + "][" + jobName + "] completed with status: " + asyncJobStatus);
 
       ///////////////////////////////////
@@ -178,29 +186,32 @@ public class AsyncRecordPipeLoop
 
 
    /*******************************************************************************
-    **
+    ** Getter for minRecordsToConsume
     *******************************************************************************/
-   @FunctionalInterface
-   public interface UnsafeFunction<T, R>
+   public Integer getMinRecordsToConsume()
    {
-      /*******************************************************************************
-       **
-       *******************************************************************************/
-      R apply(T t) throws QException;
+      return (this.minRecordsToConsume);
    }
 
 
 
    /*******************************************************************************
-    **
+    ** Setter for minRecordsToConsume
     *******************************************************************************/
-   @FunctionalInterface
-   public interface UnsafeSupplier<T>
+   public void setMinRecordsToConsume(Integer minRecordsToConsume)
    {
-      /*******************************************************************************
-       **
-       *******************************************************************************/
-      T get() throws QException;
+      this.minRecordsToConsume = minRecordsToConsume;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for minRecordsToConsume
+    *******************************************************************************/
+   public AsyncRecordPipeLoop withMinRecordsToConsume(Integer minRecordsToConsume)
+   {
+      this.minRecordsToConsume = minRecordsToConsume;
+      return (this);
    }
 
 }

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

@@ -0,0 +1,406 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.audits;
+
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.actions.AbstractQActionFunction;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.audits.AuditInput;
+import com.kingsrook.qqq.backend.core.model.actions.audits.AuditOutput;
+import com.kingsrook.qqq.backend.core.model.actions.audits.AuditSingleInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.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.RecordSecurityLock;
+import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLockFilters;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QUser;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.Pair;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Insert 1 or more audits (and optionally their children, auditDetails)
+ **
+ ** Takes care of managing the foreign key tables (auditTable, auditUser).
+ **
+ ** Enforces that security key values are provided, if the table has any.  Note that
+ ** might mean a null is given for a particular key, but at least the key must be present.
+ *******************************************************************************/
+public class AuditAction extends AbstractQActionFunction<AuditInput, AuditOutput>
+{
+   private static final QLogger LOG = QLogger.getLogger(AuditAction.class);
+
+   private Map<Pair<String, String>, Integer> cachedFetches = new HashMap<>();
+
+
+
+   /*******************************************************************************
+    ** Execute to insert 1 audit, with no details (child records)
+    *******************************************************************************/
+   public static void execute(String tableName, Integer recordId, Map<String, Serializable> securityKeyValues, String message)
+   {
+      execute(tableName, recordId, securityKeyValues, message, null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute to insert 1 audit, with a list of detail child records provided as just string messages
+    *******************************************************************************/
+   public static void executeWithStringDetails(String tableName, Integer recordId, Map<String, Serializable> securityKeyValues, String message, List<String> detailMessages)
+   {
+      List<QRecord> detailRecords = null;
+      if(CollectionUtils.nullSafeHasContents(detailMessages))
+      {
+         detailRecords = detailMessages.stream().map(m -> new QRecord().withValue("message", m)).toList();
+      }
+      execute(tableName, recordId, securityKeyValues, message, detailRecords);
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute to insert 1 audit, with a list of detail child records
+    *******************************************************************************/
+   public static void execute(String tableName, Integer recordId, Map<String, Serializable> securityKeyValues, String message, List<QRecord> details)
+   {
+      new AuditAction().execute(new AuditInput().withAuditSingleInput(new AuditSingleInput()
+         .withAuditTableName(tableName)
+         .withRecordId(recordId)
+         .withSecurityKeyValues(securityKeyValues)
+         .withMessage(message)
+         .withDetails(details)
+      ));
+   }
+
+
+
+   /*******************************************************************************
+    ** Simple overload that internally figures out primary key and security key values
+    **
+    ** Be aware - if the record doesn't have its security key values set (say it's a
+    ** partial record as part of an update), then those values won't be in the
+    ** security key map...  This should probably be considered a bug.
+    *******************************************************************************/
+   public static void appendToInput(AuditInput auditInput, QTableMetaData table, QRecord record, String auditMessage)
+   {
+      appendToInput(auditInput, table.getName(), record.getValueInteger(table.getPrimaryKeyField()), getRecordSecurityKeyValues(table, record, Optional.empty()), auditMessage);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add 1 auditSingleInput to an AuditInput object - with no details (child records).
+    *******************************************************************************/
+   public static void appendToInput(AuditInput auditInput, String tableName, Integer recordId, Map<String, Serializable> securityKeyValues, String message)
+   {
+      appendToInput(auditInput, tableName, recordId, securityKeyValues, message, null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add 1 auditSingleInput to an AuditInput object - with a list of details (child records).
+    *******************************************************************************/
+   public static AuditInput appendToInput(AuditInput auditInput, String tableName, Integer recordId, Map<String, Serializable> securityKeyValues, String message, List<QRecord> details)
+   {
+      if(auditInput == null)
+      {
+         auditInput = new AuditInput();
+      }
+
+      return auditInput.withAuditSingleInput(new AuditSingleInput()
+         .withAuditTableName(tableName)
+         .withRecordId(recordId)
+         .withSecurityKeyValues(securityKeyValues)
+         .withMessage(message)
+         .withDetails(details)
+      );
+   }
+
+
+
+   /*******************************************************************************
+    ** For a given record, from a given table, build a map of the record's security
+    ** key values.
+    **
+    ** If, in case, the record has null value(s), and the oldRecord is given (e.g.,
+    ** for the case of an update, where the record may not have all fields set, and
+    ** oldRecord should be known for doing field-diffs), then try to get the value(s)
+    ** from oldRecord.
+    **
+    ** Currently, will leave values null if they aren't found after that.
+    **
+    ** An alternative could be to re-fetch the record from its source if needed...
+    *******************************************************************************/
+   public static Map<String, Serializable> getRecordSecurityKeyValues(QTableMetaData table, QRecord record, Optional<QRecord> oldRecord)
+   {
+      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);
+      }
+      return securityKeyValues;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public AuditOutput execute(AuditInput input)
+   {
+      AuditOutput auditOutput = new AuditOutput();
+
+      if(CollectionUtils.nullSafeHasContents(input.getAuditSingleInputList()))
+      {
+         try
+         {
+            List<QRecord> auditRecords = new ArrayList<>();
+
+            for(AuditSingleInput auditSingleInput : CollectionUtils.nonNullList(input.getAuditSingleInputList()))
+            {
+               /////////////////////////////////////////
+               // validate table is known in instance //
+               /////////////////////////////////////////
+               QTableMetaData table = QContext.getQInstance().getTable(auditSingleInput.getAuditTableName());
+               if(table == null)
+               {
+                  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())))
+               {
+                  if(auditSingleInput.getSecurityKeyValues() == null || !auditSingleInput.getSecurityKeyValues().containsKey(recordSecurityLock.getSecurityKeyType()))
+                  {
+                     throw (new QException("Missing securityKeyValue [" + recordSecurityLock.getSecurityKeyType() + "] in audit request for table " + auditSingleInput.getAuditTableName()));
+                  }
+               }
+
+               ////////////////////////////////////////////////
+               // map names to ids and handle default values //
+               ////////////////////////////////////////////////
+               Integer auditTableId = getIdForName("auditTable", auditSingleInput.getAuditTableName());
+               Integer auditUserId  = getIdForName("auditUser", Objects.requireNonNullElse(auditSingleInput.getAuditUserName(), getSessionUserName()));
+               Instant timestamp    = Objects.requireNonNullElse(auditSingleInput.getTimestamp(), Instant.now());
+
+               //////////////////
+               // build record //
+               //////////////////
+               QRecord record = new QRecord()
+                  .withValue("auditTableId", auditTableId)
+                  .withValue("auditUserId", auditUserId)
+                  .withValue("timestamp", timestamp)
+                  .withValue("message", auditSingleInput.getMessage())
+                  .withValue("recordId", auditSingleInput.getRecordId());
+
+               if(auditSingleInput.getSecurityKeyValues() != null)
+               {
+                  for(Map.Entry<String, Serializable> entry : auditSingleInput.getSecurityKeyValues().entrySet())
+                  {
+                     record.setValue(entry.getKey(), entry.getValue());
+                  }
+               }
+
+               auditRecords.add(record);
+            }
+
+            /////////////////////////////
+            // do a single bulk insert //
+            /////////////////////////////
+            InsertInput insertInput = new InsertInput();
+            insertInput.setTableName("audit");
+            insertInput.setRecords(auditRecords);
+            InsertOutput insertOutput = new InsertAction().execute(insertInput);
+
+            //////////////////////////////////////////
+            // now look for children (auditDetails) //
+            //////////////////////////////////////////
+            int           i                  = 0;
+            List<QRecord> auditDetailRecords = new ArrayList<>();
+            for(AuditSingleInput auditSingleInput : CollectionUtils.nonNullList(input.getAuditSingleInputList()))
+            {
+               Integer auditId = insertOutput.getRecords().get(i++).getValueInteger("id");
+               if(auditId == null)
+               {
+                  LOG.warn("Missing an id for inserted audit - so won't be able to store its child details...");
+                  continue;
+               }
+
+               for(QRecord detail : CollectionUtils.nonNullList(auditSingleInput.getDetails()))
+               {
+                  auditDetailRecords.add(detail.withValue("auditId", auditId));
+               }
+            }
+
+            if(!auditDetailRecords.isEmpty())
+            {
+               insertInput = new InsertInput();
+               insertInput.setTableName("auditDetail");
+               insertInput.setRecords(auditDetailRecords);
+               new InsertAction().execute(insertInput);
+            }
+         }
+         catch(Exception e)
+         {
+            LOG.error("Error performing an audit", e);
+         }
+      }
+
+      return (auditOutput);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String getSessionUserName()
+   {
+      QUser user = QContext.getQSession().getUser();
+      if(user == null)
+      {
+         return ("Unknown");
+      }
+      return (user.getFullName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Integer getIdForName(String tableName, String nameValue) throws QException
+   {
+      Pair<String, String> key = new Pair<>(tableName, nameValue);
+      if(!cachedFetches.containsKey(key))
+      {
+
+         Integer id = fetchIdFromName(tableName, nameValue);
+         if(id != null)
+         {
+            cachedFetches.put(key, id);
+            return id;
+         }
+
+         try
+         {
+            LOG.debug("Inserting " + tableName + " named " + nameValue);
+            InsertInput insertInput = new InsertInput();
+            insertInput.setTableName(tableName);
+            QRecord record = new QRecord().withValue("name", nameValue);
+
+            if(tableName.equals("auditTable"))
+            {
+               QTableMetaData table = QContext.getQInstance().getTable(nameValue);
+               if(table != null)
+               {
+                  record.setValue("label", table.getLabel());
+               }
+            }
+
+            insertInput.setRecords(List.of(record));
+            InsertOutput insertOutput = new InsertAction().execute(insertInput);
+            id = insertOutput.getRecords().get(0).getValueInteger("id");
+            if(id != null)
+            {
+               cachedFetches.put(key, id);
+               return id;
+            }
+         }
+         catch(Exception e)
+         {
+            ////////////////////////////////////////////////////////////////////
+            // assume this may mean a dupe-key - so - try another fetch below //
+            ////////////////////////////////////////////////////////////////////
+            LOG.debug("Caught error inserting " + tableName + " named " + nameValue + " - will try to re-fetch", e);
+         }
+
+         id = fetchIdFromName(tableName, nameValue);
+         if(id != null)
+         {
+            cachedFetches.put(key, id);
+            return id;
+         }
+
+         /////////////
+         // give up //
+         /////////////
+         throw (new QException("Unable to get id for " + tableName + " named " + nameValue));
+      }
+
+      return (cachedFetches.get(key));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Integer fetchIdFromName(String tableName, String nameValue) throws QException
+   {
+      GetInput getInput = new GetInput();
+      getInput.setTableName(tableName);
+      getInput.setUniqueKey(Map.of("name", nameValue));
+      GetOutput getOutput = new GetAction().execute(getInput);
+      if(getOutput.getRecord() != null)
+      {
+         return (getOutput.getRecord().getValueInteger("id"));
+      }
+
+      return (null);
+   }
+
+}

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

@@ -0,0 +1,558 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.audits;
+
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.actions.AbstractQActionFunction;
+import com.kingsrook.qqq.backend.core.actions.values.QPossibleValueTranslator;
+import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.audits.AuditInput;
+import com.kingsrook.qqq.backend.core.model.actions.audits.DMLAuditInput;
+import com.kingsrook.qqq.backend.core.model.actions.audits.DMLAuditOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.audits.AuditLevel;
+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.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import static com.kingsrook.qqq.backend.core.actions.audits.AuditAction.getRecordSecurityKeyValues;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Audit for a standard DML (Data Manipulation Language) activity - e.g.,
+ ** insert, edit, or delete.
+ *******************************************************************************/
+public class DMLAuditAction extends AbstractQActionFunction<DMLAuditInput, DMLAuditOutput>
+{
+   private static final QLogger LOG = QLogger.getLogger(DMLAuditAction.class);
+
+   public static final String AUDIT_CONTEXT_FIELD_NAME = "auditContext";
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public DMLAuditOutput execute(DMLAuditInput input) throws QException
+   {
+      DMLAuditOutput           output           = new DMLAuditOutput();
+      AbstractTableActionInput tableActionInput = input.getTableActionInput();
+      List<QRecord>            oldRecordList    = input.getOldRecordList();
+      QTableMetaData           table            = tableActionInput.getTable();
+      long                     start            = System.currentTimeMillis();
+      DMLType                  dmlType          = getDMLType(tableActionInput);
+
+      try
+      {
+         List<QRecord> recordList = CollectionUtils.nonNullList(input.getRecordList()).stream()
+            .filter(r -> CollectionUtils.nullSafeIsEmpty(r.getErrors())).toList();
+
+         AuditLevel auditLevel = getAuditLevel(tableActionInput);
+         if(auditLevel == null || auditLevel.equals(AuditLevel.NONE) || CollectionUtils.nullSafeIsEmpty(recordList))
+         {
+            /////////////////////////////////////////////
+            // return with noop for null or level NONE //
+            /////////////////////////////////////////////
+            return (output);
+         }
+
+         String contextSuffix = getContentSuffix(input);
+
+         AuditInput auditInput = new AuditInput();
+         if(auditLevel.equals(AuditLevel.RECORD) || (auditLevel.equals(AuditLevel.FIELD) && !dmlType.supportsFields))
+         {
+            ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            // make many simple audits (no details) for RECORD level                                                  //
+            // or for FIELD level, but on a DML type that doesn't support field-level details (e.g., DELETE or OTHER) //
+            ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            for(QRecord record : recordList)
+            {
+               AuditAction.appendToInput(auditInput, table.getName(), record.getValueInteger(table.getPrimaryKeyField()), getRecordSecurityKeyValues(table, record, Optional.empty()), "Record was " + dmlType.pastTenseVerb + contextSuffix);
+            }
+         }
+         else if(auditLevel.equals(AuditLevel.FIELD))
+         {
+            Map<Serializable, QRecord> oldRecordMap = buildOldRecordMap(table, oldRecordList);
+
+            ///////////////////////////////////////////////////////////////////
+            // do many audits, all with field level details, for FIELD level //
+            ///////////////////////////////////////////////////////////////////
+            QPossibleValueTranslator qPossibleValueTranslator = new QPossibleValueTranslator(QContext.getQInstance(), QContext.getQSession());
+            qPossibleValueTranslator.translatePossibleValuesInRecords(table, CollectionUtils.mergeLists(recordList, oldRecordList));
+
+            //////////////////////////////////////////
+            // sort the field names by their labels //
+            //////////////////////////////////////////
+            List<String> sortedFieldNames = table.getFields().keySet().stream()
+               .sorted(Comparator.comparing(fieldName -> table.getFields().get(fieldName).getLabel()))
+               .toList();
+
+            QFieldMetaData primaryKeyField = table.getField(table.getPrimaryKeyField());
+
+            //////////////////////////////////////////////
+            // build single audit input for each record //
+            //////////////////////////////////////////////
+            for(QRecord record : recordList)
+            {
+               QRecord oldRecord = oldRecordMap.get(ValueUtils.getValueAsFieldType(primaryKeyField.getType(), record.getValue(primaryKeyField.getName())));
+
+               List<QRecord> details = new ArrayList<>();
+               for(String fieldName : sortedFieldNames)
+               {
+                  makeAuditDetailRecordForField(fieldName, table, dmlType, record, oldRecord)
+                     .ifPresent(details::add);
+               }
+
+               if(details.isEmpty() && DMLType.UPDATE.equals(dmlType))
+               {
+                  // no, let's just noop.
+                  // details.add(new QRecord().withValue("message", "No fields values were changed."));
+               }
+               else
+               {
+                  AuditAction.appendToInput(auditInput, table.getName(), record.getValueInteger(table.getPrimaryKeyField()), getRecordSecurityKeyValues(table, record, Optional.ofNullable(oldRecord)), "Record was " + dmlType.pastTenseVerb + contextSuffix, details);
+               }
+            }
+         }
+
+         // new AuditAction().executeAsync(auditInput); // todo async??? maybe get that from rules???
+         new AuditAction().execute(auditInput);
+         long end = System.currentTimeMillis();
+         LOG.trace("Audit performance", logPair("auditLevel", String.valueOf(auditLevel)), logPair("recordCount", recordList.size()), logPair("millis", (end - start)));
+      }
+      catch(Exception e)
+      {
+         LOG.error("Error performing DML audit", e, logPair("type", String.valueOf(dmlType)), logPair("table", table.getName()));
+      }
+
+      return (output);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String getContentSuffix(DMLAuditInput input)
+   {
+      StringBuilder contextSuffix = new StringBuilder();
+
+      /////////////////////////////////////////////////////////////////////////////
+      // start with context from the input wrapper                               //
+      // note, these contexts get propagated down from Input/Update/Delete Input //
+      /////////////////////////////////////////////////////////////////////////////
+      if(StringUtils.hasContent(input.getAuditContext()))
+      {
+         contextSuffix.append(" ").append(input.getAuditContext());
+      }
+
+      /////////////////////////////////////////////////////////////////////////////////////
+      // note process label (and a possible context from the process's state) if present //
+      /////////////////////////////////////////////////////////////////////////////////////
+      Optional<AbstractActionInput> actionInput = QContext.getFirstActionInStack();
+      if(actionInput.isPresent() && actionInput.get() instanceof RunProcessInput runProcessInput)
+      {
+         String processAuditContext = ValueUtils.getValueAsString(runProcessInput.getValue(AUDIT_CONTEXT_FIELD_NAME));
+         if(StringUtils.hasContent(processAuditContext))
+         {
+            contextSuffix.append(" ").append(processAuditContext);
+         }
+
+         String           processName = runProcessInput.getProcessName();
+         QProcessMetaData process     = QContext.getQInstance().getProcess(processName);
+         if(process != null)
+         {
+            contextSuffix.append(" during process: ").append(process.getLabel());
+         }
+      }
+
+      ///////////////////////////////////////////////////
+      // use api label & version if present in session //
+      ///////////////////////////////////////////////////
+      QSession qSession   = QContext.getQSession();
+      String   apiVersion = qSession.getValue("apiVersion");
+      if(apiVersion != null)
+      {
+         String apiLabel = qSession.getValue("apiLabel");
+         if(!StringUtils.hasContent(apiLabel))
+         {
+            apiLabel = "API";
+         }
+         contextSuffix.append(" via ").append(apiLabel).append(" Version: ").append(apiVersion);
+      }
+      return (contextSuffix.toString());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static Optional<QRecord> makeAuditDetailRecordForField(String fieldName, QTableMetaData table, DMLType dmlType, QRecord record, QRecord oldRecord)
+   {
+      if(!record.getValues().containsKey(fieldName))
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         // if the stored record doesn't have this field name, then don't audit anything about it      //
+         // this is to deal with our Patch style updates not looking like every field was cleared out. //
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         return (Optional.empty());
+      }
+
+      if(fieldName.equals("modifyDate") || fieldName.equals("createDate") || fieldName.equals("automationStatus"))
+      {
+         return (Optional.empty());
+      }
+
+      QFieldMetaData field        = table.getField(fieldName);
+      Serializable   value        = ValueUtils.getValueAsFieldType(field.getType(), record.getValue(fieldName));
+      Serializable   oldValue     = oldRecord == null ? null : ValueUtils.getValueAsFieldType(field.getType(), oldRecord.getValue(fieldName));
+      QRecord        detailRecord = null;
+
+      if(oldRecord == null)
+      {
+         if(DMLType.INSERT.equals(dmlType) && value == null)
+         {
+            return (Optional.empty());
+         }
+
+         if(field.getType().equals(QFieldType.BLOB) || field.getType().needsMasked())
+         {
+            detailRecord = new QRecord().withValue("message", "Set " + field.getLabel());
+         }
+         else
+         {
+            String formattedValue = getFormattedValueForAuditDetail(record, fieldName, field, value);
+            detailRecord = new QRecord().withValue("message", "Set " + field.getLabel() + " to " + formattedValue);
+            detailRecord.withValue("newValue", formattedValue);
+         }
+      }
+      else
+      {
+         if(areValuesDifferentForAudit(field, value, oldValue))
+         {
+            if(field.getType().equals(QFieldType.BLOB) || field.getType().needsMasked())
+            {
+               if(oldValue == null)
+               {
+                  detailRecord = new QRecord().withValue("message", "Set " + field.getLabel());
+               }
+               else if(value == null)
+               {
+                  detailRecord = new QRecord().withValue("message", "Removed " + field.getLabel());
+               }
+               else
+               {
+                  detailRecord = new QRecord().withValue("message", "Changed " + field.getLabel());
+               }
+            }
+            else
+            {
+               String formattedValue    = getFormattedValueForAuditDetail(record, fieldName, field, value);
+               String formattedOldValue = getFormattedValueForAuditDetail(oldRecord, fieldName, field, oldValue);
+
+               if(oldValue == null)
+               {
+                  detailRecord = new QRecord().withValue("message", "Set " + field.getLabel() + " to " + formatFormattedValueForDetailMessage(field, formattedValue));
+                  detailRecord.withValue("newValue", formattedValue);
+               }
+               else if(value == null)
+               {
+                  detailRecord = new QRecord().withValue("message", "Removed " + formatFormattedValueForDetailMessage(field, formattedOldValue) + " from " + field.getLabel());
+                  detailRecord.withValue("oldValue", formattedOldValue);
+               }
+               else
+               {
+                  detailRecord = new QRecord().withValue("message", "Changed " + field.getLabel() + " from " + formatFormattedValueForDetailMessage(field, formattedOldValue) + " to " + formatFormattedValueForDetailMessage(field, formattedValue));
+                  detailRecord.withValue("oldValue", formattedOldValue);
+                  detailRecord.withValue("newValue", formattedValue);
+               }
+            }
+         }
+      }
+
+      if(detailRecord != null)
+      {
+         ////////////////////////////////////////////////////////////////////
+         // useful if doing dev in here - but overkill for any other time. //
+         ////////////////////////////////////////////////////////////////////
+         // LOG.debug("Returning with message: " + detailRecord.getValueString("message"));
+         detailRecord.withValue("fieldName", fieldName);
+         return (Optional.of(detailRecord));
+      }
+
+      return (Optional.empty());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static boolean areValuesDifferentForAudit(QFieldMetaData field, Serializable value, Serializable oldValue)
+   {
+      try
+      {
+         ///////////////////
+         // decimal rules //
+         ///////////////////
+         if(field.getType().equals(QFieldType.DECIMAL))
+         {
+            BigDecimal newBD = ValueUtils.getValueAsBigDecimal(value);
+            BigDecimal oldBD = ValueUtils.getValueAsBigDecimal(oldValue);
+
+            if(newBD == null && oldBD == null)
+            {
+               return (false);
+            }
+
+            if(newBD == null || oldBD == null)
+            {
+               return (true);
+            }
+
+            return (newBD.compareTo(oldBD) != 0);
+         }
+
+         ////////////////////
+         // dateTime rules //
+         ////////////////////
+         if(field.getType().equals(QFieldType.DATE_TIME))
+         {
+            Instant newI = ValueUtils.getValueAsInstant(value);
+            Instant oldI = ValueUtils.getValueAsInstant(oldValue);
+
+            if(newI == null && oldI == null)
+            {
+               return (false);
+            }
+
+            if(newI == null || oldI == null)
+            {
+               return (true);
+            }
+
+            ////////////////////////////////
+            // just compare to the second //
+            ////////////////////////////////
+            return (newI.truncatedTo(ChronoUnit.SECONDS).compareTo(oldI.truncatedTo(ChronoUnit.SECONDS)) != 0);
+         }
+
+         //////////////////
+         // string rules //
+         //////////////////
+         if(field.getType().isStringLike())
+         {
+            String newString = ValueUtils.getValueAsString(value);
+            String oldString = ValueUtils.getValueAsString(oldValue);
+
+            boolean newIsNullOrEmpty = !StringUtils.hasContent(newString);
+            boolean oldIsNullOrEmpty = !StringUtils.hasContent(oldString);
+
+            if(newIsNullOrEmpty && oldIsNullOrEmpty)
+            {
+               return (false);
+            }
+
+            if(newIsNullOrEmpty || oldIsNullOrEmpty)
+            {
+               return (true);
+            }
+
+            return (newString.compareTo(oldString) != 0);
+         }
+
+         /////////////////////////////////////
+         // default just use Objects.equals //
+         /////////////////////////////////////
+         return !Objects.equals(oldValue, value);
+      }
+      catch(Exception e)
+      {
+         LOG.debug("Error checking areValuesDifferentForAudit", e, logPair("fieldName", field.getName()), logPair("value", value), logPair("oldValue", oldValue));
+      }
+
+      ////////////////////////////////////
+      // default to something simple... //
+      ////////////////////////////////////
+      return !Objects.equals(oldValue, value);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String getFormattedValueForAuditDetail(QRecord record, String fieldName, QFieldMetaData field, Serializable value)
+   {
+      String formattedValue = null;
+      if(value != null)
+      {
+         if(field.getType().equals(QFieldType.DATE_TIME) && value instanceof Instant instant)
+         {
+            formattedValue = QValueFormatter.formatDateTimeWithZone(instant.atZone(ZoneId.of(Objects.requireNonNullElse(QContext.getQInstance().getDefaultTimeZoneId(), "UTC"))));
+         }
+         else if(record.getDisplayValue(fieldName) != null)
+         {
+            formattedValue = record.getDisplayValue(fieldName);
+         }
+         else
+         {
+            formattedValue = QValueFormatter.formatValue(field, value);
+         }
+      }
+
+      return formattedValue;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String formatFormattedValueForDetailMessage(QFieldMetaData field, String formattedValue)
+   {
+      if(formattedValue == null || "null".equals(formattedValue))
+      {
+         formattedValue = "--";
+      }
+      else
+      {
+         if(QFieldType.STRING.equals(field.getType()) || field.getPossibleValueSourceName() != null)
+         {
+            formattedValue = '"' + formattedValue + '"';
+         }
+      }
+
+      return (formattedValue);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Map<Serializable, QRecord> buildOldRecordMap(QTableMetaData table, List<QRecord> oldRecordList)
+   {
+      Map<Serializable, QRecord> rs = new HashMap<>();
+      for(QRecord record : CollectionUtils.nonNullList(oldRecordList))
+      {
+         rs.put(record.getValue(table.getPrimaryKeyField()), record);
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private DMLType getDMLType(AbstractTableActionInput tableActionInput)
+   {
+      if(tableActionInput instanceof InsertInput)
+      {
+         return DMLType.INSERT;
+      }
+      else if(tableActionInput instanceof UpdateInput)
+      {
+         return DMLType.UPDATE;
+      }
+      else if(tableActionInput instanceof DeleteInput)
+      {
+         return DMLType.DELETE;
+      }
+      else
+      {
+         return DMLType.OTHER;
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static AuditLevel getAuditLevel(AbstractTableActionInput tableActionInput)
+   {
+      QTableMetaData table = tableActionInput.getTable();
+      if(table.getAuditRules() == null)
+      {
+         return (AuditLevel.NONE);
+      }
+
+      return (table.getAuditRules().getAuditLevel());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   enum DMLType
+   {
+      INSERT("Inserted", true),
+      UPDATE("Edited", true),
+      DELETE("Deleted", false),
+      OTHER("Processed", false);
+
+      private final String  pastTenseVerb;
+      private final boolean supportsFields;
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      DMLType(String pastTenseVerb, boolean supportsFields)
+      {
+         this.pastTenseVerb = pastTenseVerb;
+         this.supportsFields = supportsFields;
+      }
+   }
+}

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

@@ -22,12 +22,20 @@
 package com.kingsrook.qqq.backend.core.actions.automation;
 
 
-import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
-import java.util.Objects;
+import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.automation.TableTrigger;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
@@ -37,7 +45,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TableAuto
 import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TriggerEvent;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
-import com.kingsrook.qqq.backend.core.utils.QLogger;
 import org.apache.commons.lang.NotImplementedException;
 
 
@@ -76,12 +83,16 @@ public class RecordAutomationStatusUpdater
             String className = stackTraceElement.getClassName();
             if(className.contains("com.kingsrook.qqq.backend.core.actions.automation") && !className.equals(RecordAutomationStatusUpdater.class.getName()) && !className.endsWith("Test"))
             {
-               LOG.debug(session, "Avoiding re-setting automation status to PENDING_UPDATE while running an automation");
+               LOG.debug("Avoiding re-setting automation status to PENDING_UPDATE while running an automation");
                return (false);
             }
          }
       }
 
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // Avoid setting records to PENDING_INSERT or PENDING_UPDATE even if they don't have any insert or update automations or triggers //
+      // such records should go straight to OK status.                                                                                  //
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
       if(canWeSkipPendingAndGoToOkay(table, automationStatus))
       {
          automationStatus = AutomationStatus.OK;
@@ -92,6 +103,12 @@ public class RecordAutomationStatusUpdater
       {
          for(QRecord record : records)
          {
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            // todo - seems like there's some case here, where if an order was in PENDING_INSERT, but then some other job updated the record, that we'd  //
+            //  lose that pending status, which would be a Bad Thing™...                                                                                 //
+            //  problem is - we may not have the full record in here, so we can't necessarily check the record to see what status it's currently in...   //
+            ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
             record.setValue(automationDetails.getStatusTracking().getFieldName(), automationStatus.getId());
             // todo - another field - for the automation timestamp??
          }
@@ -107,20 +124,91 @@ public class RecordAutomationStatusUpdater
     ** being asked to set status to PENDING_INSERT (or PENDING_UPDATE), then just
     ** move the status straight to OK.
     *******************************************************************************/
-   private static boolean canWeSkipPendingAndGoToOkay(QTableMetaData table, AutomationStatus automationStatus)
+   static boolean canWeSkipPendingAndGoToOkay(QTableMetaData table, AutomationStatus automationStatus)
    {
-      List<TableAutomationAction> tableActions = Objects.requireNonNullElse(table.getAutomationDetails().getActions(), new ArrayList<>());
+      List<TableAutomationAction> tableActions = Collections.emptyList();
+      if(table.getAutomationDetails() != null && table.getAutomationDetails().getActions() != null)
+      {
+         tableActions = table.getAutomationDetails().getActions();
+      }
 
       if(automationStatus.equals(AutomationStatus.PENDING_INSERT_AUTOMATIONS))
       {
-         return tableActions.stream().noneMatch(a -> TriggerEvent.POST_INSERT.equals(a.getTriggerEvent()));
+         if(tableActions.stream().anyMatch(a -> TriggerEvent.POST_INSERT.equals(a.getTriggerEvent())))
+         {
+            return (false);
+         }
+         else if(areThereTableTriggersForTable(table, TriggerEvent.POST_INSERT))
+         {
+            return (false);
+         }
+
+         ////////////////////////////////////////////////////////////////////////////////////////
+         // if we're going to pending-insert, and there are no insert automations or triggers, //
+         // then we may skip pending and go to okay.                                           //
+         ////////////////////////////////////////////////////////////////////////////////////////
+         return (true);
       }
       else if(automationStatus.equals(AutomationStatus.PENDING_UPDATE_AUTOMATIONS))
       {
-         return tableActions.stream().noneMatch(a -> TriggerEvent.POST_UPDATE.equals(a.getTriggerEvent()));
+         if(tableActions.stream().anyMatch(a -> TriggerEvent.POST_UPDATE.equals(a.getTriggerEvent())))
+         {
+            return (false);
+         }
+         else if(areThereTableTriggersForTable(table, TriggerEvent.POST_UPDATE))
+         {
+            return (false);
+         }
+
+         ////////////////////////////////////////////////////////////////////////////////////////
+         // if we're going to pending-update, and there are no insert automations or triggers, //
+         // then we may skip pending and go to okay.                                           //
+         ////////////////////////////////////////////////////////////////////////////////////////
+         return (true);
+      }
+      else
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if we're going to any other automation status - then we may never "skip pending" and go to okay - //
+         // because we weren't asked to go to pending!                                                        //
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static boolean areThereTableTriggersForTable(QTableMetaData table, TriggerEvent triggerEvent)
+   {
+      if(QContext.getQInstance().getTable(TableTrigger.TABLE_NAME) == null)
+      {
+         return (false);
       }
 
-      return (false);
+      try
+      {
+         ///////////////////
+         // todo - cache? //
+         ///////////////////
+         CountInput countInput = new CountInput();
+         countInput.setTableName(TableTrigger.TABLE_NAME);
+         countInput.setFilter(new QQueryFilter(
+            new QFilterCriteria("tableName", QCriteriaOperator.EQUALS, table.getName()),
+            new QFilterCriteria(triggerEvent.equals(TriggerEvent.POST_INSERT) ? "postInsert" : "postUpdate", QCriteriaOperator.EQUALS, true)
+         ));
+         CountOutput countOutput = new CountAction().execute(countInput);
+         return (countOutput.getCount() != null && countOutput.getCount() > 0);
+      }
+      catch(Exception e)
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if the count query failed, we're a bit safer to err on the side of "yeah, there might be automations" //
+         ///////////////////////////////////////////////////////////////////////////////////////////////////////////
+         return (true);
+      }
    }
 
 
@@ -137,8 +225,7 @@ public class RecordAutomationStatusUpdater
          boolean didSetStatusField = setAutomationStatusInRecords(session, table, records, automationStatus);
          if(didSetStatusField)
          {
-            UpdateInput updateInput = new UpdateInput(instance);
-            updateInput.setSession(session);
+            UpdateInput updateInput = new UpdateInput();
             updateInput.setTableName(table.getName());
 
             /////////////////////////////////////////////////////////////////////////////////////
@@ -150,6 +237,7 @@ public class RecordAutomationStatusUpdater
                .withValue(table.getPrimaryKeyField(), r.getValue(table.getPrimaryKeyField()))
                .withValue(automationDetails.getStatusTracking().getFieldName(), r.getValue(automationDetails.getStatusTracking().getFieldName()))).toList());
             updateInput.setAreAllValuesBeingUpdatedTheSame(true);
+            updateInput.setOmitDmlAudit(true);
 
             new UpdateAction().execute(updateInput);
          }

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

@@ -0,0 +1,96 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.automation;
+
+
+import java.io.Serializable;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.scripts.RunAdHocRecordScriptAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryJoin;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
+import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.AdHocScriptCodeReference;
+import com.kingsrook.qqq.backend.core.model.scripts.Script;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptsMetaDataProvider;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class RunRecordScriptAutomationHandler extends RecordAutomationHandler
+{
+   private static final QLogger LOG = QLogger.getLogger(RunRecordScriptAutomationHandler.class);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void execute(RecordAutomationInput recordAutomationInput) throws QException
+   {
+      String                    tableName = recordAutomationInput.getTableName();
+      Map<String, Serializable> values    = recordAutomationInput.getAction().getValues();
+      Integer                   scriptId  = ValueUtils.getValueAsInteger(values.get("scriptId"));
+
+      if(scriptId == null)
+      {
+         throw (new QException("ScriptId was not provided in values map for record automations on table: " + tableName));
+      }
+
+      QueryInput queryInput = new QueryInput();
+      queryInput.setTableName(ScriptRevision.TABLE_NAME);
+      queryInput.setFilter(new QQueryFilter(new QFilterCriteria("scriptId", QCriteriaOperator.EQUALS, scriptId)));
+      queryInput.withQueryJoin(new QueryJoin(Script.TABLE_NAME).withBaseTableOrAlias(ScriptRevision.TABLE_NAME).withJoinMetaData(QContext.getQInstance().getJoin(ScriptsMetaDataProvider.CURRENT_SCRIPT_REVISION_JOIN_NAME)));
+      QueryOutput queryOutput = new QueryAction().execute(queryInput);
+      if(CollectionUtils.nullSafeIsEmpty(queryOutput.getRecords()))
+      {
+         throw (new QException("Could not find current revision for scriptId: " + scriptId + " on table " + tableName));
+      }
+
+      QRecord scriptRevision = queryOutput.getRecords().get(0);
+      LOG.info("Running script against records", logPair("scriptRevisionId", scriptRevision.getValue("id")), logPair("scriptId", scriptRevision.getValue("scriptIdd")));
+
+      RunAdHocRecordScriptInput input = new RunAdHocRecordScriptInput();
+      input.setCodeReference(new AdHocScriptCodeReference().withScriptRevisionRecord(scriptRevision));
+      input.setTableName(tableName);
+      input.setRecordList(recordAutomationInput.getRecordList());
+      RunAdHocRecordScriptOutput output = new RunAdHocRecordScriptOutput();
+      new RunAdHocRecordScriptAction().run(input, output);
+   }
+
+}

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

@@ -25,42 +25,53 @@ package com.kingsrook.qqq.backend.core.actions.automation.polling;
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.Comparator;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncRecordPipeLoop;
 import com.kingsrook.qqq.backend.core.actions.automation.AutomationStatus;
 import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler;
 import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationStatusUpdater;
+import com.kingsrook.qqq.backend.core.actions.automation.RunRecordScriptAutomationHandler;
 import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
 import com.kingsrook.qqq.backend.core.actions.processes.QProcessCallback;
 import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
 import com.kingsrook.qqq.backend.core.actions.reporting.RecordPipe;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
 import com.kingsrook.qqq.backend.core.model.automation.RecordAutomationInput;
+import com.kingsrook.qqq.backend.core.model.automation.TableTrigger;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 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.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.AutomationStatusTrackingType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.QTableAutomationDetails;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TableAutomationAction;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TriggerEvent;
+import com.kingsrook.qqq.backend.core.model.savedfilters.SavedFilter;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
-import com.kingsrook.qqq.backend.core.scheduler.StandardScheduledExecutor;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.collections.MapBuilder;
 import org.apache.commons.lang.NotImplementedException;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -74,7 +85,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class PollingAutomationPerTableRunner implements Runnable
 {
-   private static final Logger LOG = LogManager.getLogger(PollingAutomationPerTableRunner.class);
+   private static final QLogger LOG = QLogger.getLogger(PollingAutomationPerTableRunner.class);
 
    private final TableActions tableActions;
    private final String       name;
@@ -87,6 +98,11 @@ public class PollingAutomationPerTableRunner implements Runnable
       TriggerEvent.POST_UPDATE, AutomationStatus.PENDING_UPDATE_AUTOMATIONS
    );
 
+   private static Map<AutomationStatus, TriggerEvent> automationStatusTriggerEventMap = Map.of(
+      AutomationStatus.PENDING_INSERT_AUTOMATIONS, TriggerEvent.POST_INSERT,
+      AutomationStatus.PENDING_UPDATE_AUTOMATIONS, TriggerEvent.POST_UPDATE
+   );
+
    private static Map<AutomationStatus, AutomationStatus> pendingToRunningStatusMap = Map.of(
       AutomationStatus.PENDING_INSERT_AUTOMATIONS, AutomationStatus.RUNNING_INSERT_AUTOMATIONS,
       AutomationStatus.PENDING_UPDATE_AUTOMATIONS, AutomationStatus.RUNNING_UPDATE_AUTOMATIONS
@@ -102,51 +118,26 @@ public class PollingAutomationPerTableRunner implements Runnable
    /*******************************************************************************
     **
     *******************************************************************************/
-   public record TableActions(String tableName, AutomationStatus status, List<TableAutomationAction> actions)
+   public record TableActions(String tableName, AutomationStatus status)
    {
    }
 
 
 
    /*******************************************************************************
-    **
+    ** basically just get a list of tables which at least *could* have automations
+    ** run - either meta-data automations, or table-triggers (data/user defined).
     *******************************************************************************/
    public static List<TableActions> getTableActions(QInstance instance, String providerName)
    {
-      Map<String, Map<AutomationStatus, List<TableAutomationAction>>> workingTableActionMap = new HashMap<>();
-      List<TableActions>                                              tableActionList       = new ArrayList<>();
+      List<TableActions> tableActionList = new ArrayList<>();
 
-      //////////////////////////////////////////////////////////////////////
-      // todo - share logic like this among any automation implementation //
-      //////////////////////////////////////////////////////////////////////
       for(QTableMetaData table : instance.getTables().values())
       {
          if(table.getAutomationDetails() != null && providerName.equals(table.getAutomationDetails().getProviderName()))
          {
-            ///////////////////////////////////////////////////////////////////////////
-            // organize the table's actions by type                                  //
-            // todo - in future, need user-defined actions here too (and refreshed!) //
-            ///////////////////////////////////////////////////////////////////////////
-            for(TableAutomationAction action : table.getAutomationDetails().getActions())
-            {
-               AutomationStatus automationStatus = triggerEventAutomationStatusMap.get(action.getTriggerEvent());
-               workingTableActionMap.putIfAbsent(table.getName(), new HashMap<>());
-               workingTableActionMap.get(table.getName()).putIfAbsent(automationStatus, new ArrayList<>());
-               workingTableActionMap.get(table.getName()).get(automationStatus).add(action);
-            }
-
-            ////////////////////////////////////////////
-            // convert the map to tableAction records //
-            ////////////////////////////////////////////
-            for(Map.Entry<AutomationStatus, List<TableAutomationAction>> entry : workingTableActionMap.get(table.getName()).entrySet())
-            {
-               AutomationStatus            automationStatus = entry.getKey();
-               List<TableAutomationAction> actionList       = entry.getValue();
-
-               actionList.sort(Comparator.comparing(TableAutomationAction::getPriority));
-
-               tableActionList.add(new TableActions(table.getName(), automationStatus, actionList));
-            }
+            tableActionList.add(new TableActions(table.getName(), AutomationStatus.PENDING_INSERT_AUTOMATIONS));
+            tableActionList.add(new TableActions(table.getName(), AutomationStatus.PENDING_UPDATE_AUTOMATIONS));
          }
       }
 
@@ -174,14 +165,16 @@ public class PollingAutomationPerTableRunner implements Runnable
    @Override
    public void run()
    {
+      QContext.init(instance, sessionSupplier.get());
+
       String originalThreadName = Thread.currentThread().getName();
-      Thread.currentThread().setName(name + StandardScheduledExecutor.newThreadNameRandomSuffix());
+      Thread.currentThread().setName(name);
       LOG.debug("Running " + this.getClass().getSimpleName() + "[" + name + "]");
 
       try
       {
          QSession session = sessionSupplier != null ? sessionSupplier.get() : new QSession();
-         processTableInsertOrUpdate(instance.getTable(tableActions.tableName()), session, tableActions.status(), tableActions.actions());
+         processTableInsertOrUpdate(instance.getTable(tableActions.tableName()), session, tableActions.status());
       }
       catch(Exception e)
       {
@@ -190,6 +183,7 @@ public class PollingAutomationPerTableRunner implements Runnable
       finally
       {
          Thread.currentThread().setName(originalThreadName);
+         QContext.clear();
       }
    }
 
@@ -198,8 +192,12 @@ public class PollingAutomationPerTableRunner implements Runnable
    /*******************************************************************************
     ** Query for and process records that have a PENDING_INSERT or PENDING_UPDATE status on a given table.
     *******************************************************************************/
-   private void processTableInsertOrUpdate(QTableMetaData table, QSession session, AutomationStatus automationStatus, List<TableAutomationAction> actions) throws QException
+   public void processTableInsertOrUpdate(QTableMetaData table, QSession session, AutomationStatus automationStatus) throws QException
    {
+      /////////////////////////////////////////////////////////////////////////
+      // get the actions to run against this table in this automation status //
+      /////////////////////////////////////////////////////////////////////////
+      List<TableAutomationAction> actions = getTableActions(table, automationStatus);
       if(CollectionUtils.nullSafeIsEmpty(actions))
       {
          return;
@@ -210,18 +208,21 @@ public class PollingAutomationPerTableRunner implements Runnable
       ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
       // run an async-pipe loop - that will query for records in PENDING - put them in a pipe - then apply actions to them //
       ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-      RecordPipe          recordPipe          = new RecordPipe();
-      AsyncRecordPipeLoop asyncRecordPipeLoop = new AsyncRecordPipeLoop();
+      QTableAutomationDetails automationDetails   = table.getAutomationDetails();
+      AsyncRecordPipeLoop     asyncRecordPipeLoop = new AsyncRecordPipeLoop();
+
+      RecordPipe recordPipe = automationDetails.getOverrideBatchSize() == null
+         ? new RecordPipe() : new RecordPipe(automationDetails.getOverrideBatchSize());
+
       asyncRecordPipeLoop.run("PollingAutomationRunner>Query>" + automationStatus + ">" + table.getName(), null, recordPipe, (status) ->
          {
-            QueryInput queryInput = new QueryInput(instance);
-            queryInput.setSession(session);
+            QueryInput queryInput = new QueryInput();
             queryInput.setTableName(table.getName());
 
-            AutomationStatusTrackingType statusTrackingType = table.getAutomationDetails().getStatusTracking().getType();
+            AutomationStatusTrackingType statusTrackingType = automationDetails.getStatusTracking().getType();
             if(AutomationStatusTrackingType.FIELD_IN_TABLE.equals(statusTrackingType))
             {
-               queryInput.setFilter(new QQueryFilter().withCriteria(new QFilterCriteria(table.getAutomationDetails().getStatusTracking().getFieldName(), QCriteriaOperator.EQUALS, List.of(automationStatus.getId()))));
+               queryInput.setFilter(new QQueryFilter().withCriteria(new QFilterCriteria(automationDetails.getStatusTracking().getFieldName(), QCriteriaOperator.EQUALS, List.of(automationStatus.getId()))));
             }
             else
             {
@@ -241,6 +242,83 @@ public class PollingAutomationPerTableRunner implements Runnable
 
 
 
+   /*******************************************************************************
+    ** get the actions to run against a table in an automation status.  both from
+    ** metaData and tableTriggers/data.
+    *******************************************************************************/
+   private List<TableAutomationAction> getTableActions(QTableMetaData table, AutomationStatus automationStatus) throws QException
+   {
+      List<TableAutomationAction> rs           = new ArrayList<>();
+      TriggerEvent                triggerEvent = automationStatusTriggerEventMap.get(automationStatus);
+
+      ///////////////////////////////////////////////////////////
+      // start with any actions defined in the table meta data //
+      ///////////////////////////////////////////////////////////
+      for(TableAutomationAction action : table.getAutomationDetails().getActions())
+      {
+         if(action.getTriggerEvent().equals(triggerEvent))
+         {
+            rs.add(action);
+         }
+      }
+
+      /////////////////////////////////////////////////
+      // next add any tableTriggers, defined in data //
+      /////////////////////////////////////////////////
+      if(QContext.getQInstance().getTable(TableTrigger.TABLE_NAME) != null)
+      {
+         QueryInput queryInput = new QueryInput();
+         queryInput.setTableName(TableTrigger.TABLE_NAME);
+         queryInput.setFilter(new QQueryFilter(
+            new QFilterCriteria("tableName", QCriteriaOperator.EQUALS, table.getName()),
+            new QFilterCriteria(triggerEvent.equals(TriggerEvent.POST_INSERT) ? "postInsert" : "postUpdate", QCriteriaOperator.EQUALS, true)
+         ));
+         QueryOutput queryOutput = new QueryAction().execute(queryInput);
+         for(QRecord record : queryOutput.getRecords())
+         {
+            TableTrigger tableTrigger = new TableTrigger(record);
+
+            try
+            {
+               QQueryFilter filter   = null;
+               Integer      filterId = tableTrigger.getFilterId();
+               if(filterId != null)
+               {
+                  GetInput getInput = new GetInput();
+                  getInput.setTableName(SavedFilter.TABLE_NAME);
+                  getInput.setPrimaryKey(filterId);
+                  GetOutput getOutput = new GetAction().execute(getInput);
+                  if(getOutput.getRecord() != null)
+                  {
+                     SavedFilter savedFilter = new SavedFilter(getOutput.getRecord());
+                     filter = JsonUtils.toObject(savedFilter.getFilterJson(), QQueryFilter.class);
+                  }
+               }
+
+               rs.add(new TableAutomationAction()
+                  .withName("Script:" + tableTrigger.getScriptId())
+                  .withFilter(filter)
+                  .withTriggerEvent(triggerEvent)
+                  .withPriority(tableTrigger.getPriority())
+                  .withCodeReference(new QCodeReference(RunRecordScriptAutomationHandler.class))
+                  .withValues(MapBuilder.of("scriptId", tableTrigger.getScriptId()))
+                  .withIncludeRecordAssociations(true)
+               );
+            }
+            catch(Exception e)
+            {
+               LOG.error("Error setting up table trigger", e, logPair("tableTriggerId", tableTrigger.getId()));
+            }
+         }
+      }
+
+      rs.sort(Comparator.comparing(taa -> Objects.requireNonNullElse(taa.getPriority(), Integer.MAX_VALUE)));
+
+      return (rs);
+   }
+
+
+
    /*******************************************************************************
     ** For a set of records that were found to be in a PENDING state - run all the
     ** table's actions against them - IF they are found to match the action's filter
@@ -264,22 +342,9 @@ public class PollingAutomationPerTableRunner implements Runnable
       boolean anyActionsFailed = false;
       for(TableAutomationAction action : actions)
       {
-         try
+         boolean hadError = applyActionToRecords(table, records, action);
+         if(hadError)
          {
-            //////////////////////////////////////////////////////////////////////////////////////////////////////////////
-            // note - this method - will re-query the objects, so we should have confidence that their data is fresh... //
-            //////////////////////////////////////////////////////////////////////////////////////////////////////////////
-            List<QRecord> matchingQRecords = getRecordsMatchingActionFilter(session, table, records, action);
-            LOG.debug("Of the {} records that were pending automations, {} of them match the filter on the action {}", records.size(), matchingQRecords.size(), action);
-            if(CollectionUtils.nullSafeHasContents(matchingQRecords))
-            {
-               LOG.debug("  Processing " + matchingQRecords.size() + " records in " + table + " for action " + action);
-               applyActionToMatchingRecords(session, table, matchingQRecords, action);
-            }
-         }
-         catch(Exception e)
-         {
-            LOG.warn("Caught exception processing records on " + table + " for action " + action, e);
             anyActionsFailed = true;
          }
       }
@@ -299,6 +364,37 @@ public class PollingAutomationPerTableRunner implements Runnable
 
 
 
+   /*******************************************************************************
+    ** Run one action over a list of records (if they match the action's filter).
+    **
+    ** @return hadError - true if an exception was caught; false if all OK.
+    *******************************************************************************/
+   protected boolean applyActionToRecords(QTableMetaData table, List<QRecord> records, TableAutomationAction action)
+   {
+      try
+      {
+         //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // note - this method - will re-query the objects, so we should have confidence that their data is fresh... //
+         //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         List<QRecord> matchingQRecords = getRecordsMatchingActionFilter(table, records, action);
+         LOG.debug("Of the {} records that were pending automations, {} of them match the filter on the action {}", records.size(), matchingQRecords.size(), action);
+         if(CollectionUtils.nullSafeHasContents(matchingQRecords))
+         {
+            LOG.debug("  Processing " + matchingQRecords.size() + " records in " + table + " for action " + action);
+            applyActionToMatchingRecords(table, matchingQRecords, action);
+         }
+
+         return (false);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Caught exception processing records on " + table + " for action " + action, e);
+         return (true);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** For a given action, and a list of records - return a new list, of the ones
     ** which match the action's filter (if there is one - if not, then all match).
@@ -311,32 +407,34 @@ public class PollingAutomationPerTableRunner implements Runnable
     ** but that will almost certainly give potentially different results than a true
     ** backend - e.g., just consider if the DB is case-sensitive for strings...
     *******************************************************************************/
-   private List<QRecord> getRecordsMatchingActionFilter(QSession session, QTableMetaData table, List<QRecord> records, TableAutomationAction action) throws QException
+   private List<QRecord> getRecordsMatchingActionFilter(QTableMetaData table, List<QRecord> records, TableAutomationAction action) throws QException
    {
-      QueryInput queryInput = new QueryInput(instance);
-      queryInput.setSession(session);
+      QueryInput queryInput = new QueryInput();
       queryInput.setTableName(table.getName());
 
+      ///////////////////////////////////////////////////////////////////////////////////////
+      // set up a filter that is for the primary keys IN the list that we identified above //
+      ///////////////////////////////////////////////////////////////////////////////////////
       QQueryFilter filter = new QQueryFilter();
+      filter.addCriteria(new QFilterCriteria(table.getPrimaryKeyField(), QCriteriaOperator.IN, records.stream().map(r -> r.getValue(table.getPrimaryKeyField())).toList()));
 
-      /////////////////////////////////////////////////////////////////////////////////////////////////////
-      // copy filter criteria from the action's filter to a new filter that we'll run here.              //
-      // Critically - don't modify the filter object on the action!  as that object has a long lifespan. //
-      /////////////////////////////////////////////////////////////////////////////////////////////////////
       if(action.getFilter() != null)
       {
-         if(action.getFilter().getCriteria() != null)
-         {
-            action.getFilter().getCriteria().forEach(filter::addCriteria);
-         }
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if the action defines a filter of its own, add that to the filter we'll run now as a sub-filter //
+         // not entirely clear if this needs to be a clone, but, it feels safe and cheap enough             //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////
+         filter.addSubFilter(action.getFilter().clone());
+
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // we also want to set order-bys from the action into our filter (since they only apply at the top-level) //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////
          if(action.getFilter().getOrderBys() != null)
          {
             action.getFilter().getOrderBys().forEach(filter::addOrderBy);
          }
       }
 
-      filter.addCriteria(new QFilterCriteria(table.getPrimaryKeyField(), QCriteriaOperator.IN, records.stream().map(r -> r.getValue(table.getPrimaryKeyField())).toList()));
-
       /////////////////////////////////////////////////////////////////////////////////////////////
       // always add order-by the primary key, to give more predictable/consistent results        //
       // todo - in future - if this becomes a source of slowness, make this a config to opt-out? //
@@ -345,6 +443,8 @@ public class PollingAutomationPerTableRunner implements Runnable
 
       queryInput.setFilter(filter);
 
+      queryInput.setIncludeAssociations(action.getIncludeRecordAssociations());
+
       return (new QueryAction().execute(queryInput).getRecords());
    }
 
@@ -352,8 +452,9 @@ public class PollingAutomationPerTableRunner implements Runnable
 
    /*******************************************************************************
     ** Finally, actually run action code against a list of known matching records.
+    ** todo not commit - move to somewhere genericer
     *******************************************************************************/
-   private void applyActionToMatchingRecords(QSession session, QTableMetaData table, List<QRecord> records, TableAutomationAction action) throws Exception
+   public static void applyActionToMatchingRecords(QTableMetaData table, List<QRecord> records, TableAutomationAction action) throws Exception
    {
       if(StringUtils.hasContent(action.getProcessName()))
       {
@@ -362,8 +463,7 @@ public class PollingAutomationPerTableRunner implements Runnable
          // tell it to SKIP frontend steps.                                                     //
          // give the process a callback w/ a query filter that has the p-keys of these records. //
          /////////////////////////////////////////////////////////////////////////////////////////
-         RunProcessInput runProcessInput = new RunProcessInput(instance);
-         runProcessInput.setSession(session);
+         RunProcessInput runProcessInput = new RunProcessInput();
          runProcessInput.setProcessName(action.getProcessName());
          runProcessInput.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP);
          runProcessInput.setCallback(new QProcessCallback()
@@ -376,20 +476,29 @@ public class PollingAutomationPerTableRunner implements Runnable
             }
          });
 
-         RunProcessAction runProcessAction = new RunProcessAction();
-         RunProcessOutput runProcessOutput = runProcessAction.execute(runProcessInput);
-         if(runProcessOutput.getException().isPresent())
+         try
          {
-            throw (runProcessOutput.getException().get());
+            QContext.pushAction(runProcessInput);
+
+            RunProcessAction runProcessAction = new RunProcessAction();
+            RunProcessOutput runProcessOutput = runProcessAction.execute(runProcessInput);
+            if(runProcessOutput.getException().isPresent())
+            {
+               throw (runProcessOutput.getException().get());
+            }
+         }
+         finally
+         {
+            QContext.popAction();
          }
       }
       else if(action.getCodeReference() != null)
       {
          LOG.debug("    Executing action: [" + action.getName() + "] as code reference: " + action.getCodeReference());
-         RecordAutomationInput input = new RecordAutomationInput(instance);
-         input.setSession(session);
+         RecordAutomationInput input = new RecordAutomationInput();
          input.setTableName(table.getName());
          input.setRecordList(records);
+         input.setAction(action);
 
          RecordAutomationHandler recordAutomationHandler = QCodeLoader.getRecordAutomationHandler(action);
          recordAutomationHandler.execute(input);

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

@@ -0,0 +1,82 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions after a delete takes place.
+ **
+ ** General implementation would be, to iterate over the records (ones which didn't
+ ** have a delete error), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records?
+ ** - possibly throwing an exception - though doing so won't stop the delete, and instead
+ **   will just set a warning on all of the deleted records...
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) that you want to go back
+ **   to the caller - this is how errors and warnings are propagated .
+ **
+ ** Note that the full deleteInput is available as a field in this class.
+ **
+ ** A future enhancement here may be to take (as fields in this class) the list of
+ ** records that the delete action marked in error - the user might want to do
+ ** something special with them (idk, try some other way to delete them?)
+ *******************************************************************************/
+public abstract class AbstractPostDeleteCustomizer
+{
+   protected DeleteInput deleteInput;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Getter for deleteInput
+    **
+    *******************************************************************************/
+   public DeleteInput getDeleteInput()
+   {
+      return deleteInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for deleteInput
+    **
+    *******************************************************************************/
+   public void setDeleteInput(DeleteInput deleteInput)
+   {
+      this.deleteInput = deleteInput;
+   }
+}

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

@@ -0,0 +1,77 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions after an insert takes place.
+ **
+ ** General implementation would be, to iterate over the records (the outputs of
+ ** the insert action), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records
+ ** - possibly throwing an exception - though doing so won't stop the update, and instead
+ **   will just set a warning on all of the updated records...
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) that you want to go back to the caller.
+ **
+ ** Note that the full insertInput is available as a field in this class.
+ *******************************************************************************/
+public abstract class AbstractPostInsertCustomizer
+{
+   protected InsertInput insertInput;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Getter for insertInput
+    **
+    *******************************************************************************/
+   public InsertInput getInsertInput()
+   {
+      return insertInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for insertInput
+    **
+    *******************************************************************************/
+   public void setInsertInput(InsertInput insertInput)
+   {
+      this.insertInput = insertInput;
+   }
+}

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

@@ -0,0 +1,65 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public abstract class AbstractPostQueryCustomizer
+{
+   protected AbstractTableActionInput input;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records);
+
+
+
+   /*******************************************************************************
+    ** Getter for input
+    **
+    *******************************************************************************/
+   public AbstractTableActionInput getInput()
+   {
+      return (input);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for input
+    **
+    *******************************************************************************/
+   public void setInput(AbstractTableActionInput input)
+   {
+      this.input = input;
+   }
+}

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

@@ -0,0 +1,130 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions after an update takes place.
+ **
+ ** General implementation would be, to iterate over the records (the outputs of
+ ** the update action), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records?
+ ** - possibly throwing an exception - though doing so won't stop the update, and instead
+ **   will just set a warning on all of the updated records...
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) that you want to go back to the caller.
+ **
+ ** Note that the full updateInput is available as a field in this class, and the
+ ** "old records" (e.g., with values freshly fetched from the backend) will be
+ ** available (if the backend supports it) - both as a list (`getOldRecordList`)
+ ** and as a memoized (by this class) map of primaryKey to record (`getOldRecordMap`).
+ *******************************************************************************/
+public abstract class AbstractPostUpdateCustomizer
+{
+   protected UpdateInput   updateInput;
+   protected List<QRecord> oldRecordList;
+
+   private Map<Serializable, QRecord> oldRecordMap = null;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Getter for updateInput
+    **
+    *******************************************************************************/
+   public UpdateInput getUpdateInput()
+   {
+      return updateInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updateInput
+    **
+    *******************************************************************************/
+   public void setUpdateInput(UpdateInput updateInput)
+   {
+      this.updateInput = updateInput;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void setOldRecordList(List<QRecord> oldRecordList)
+   {
+      this.oldRecordList = oldRecordList;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public List<QRecord> getOldRecordList()
+   {
+      return oldRecordList;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   protected Map<Serializable, QRecord> getOldRecordMap()
+   {
+      if(oldRecordMap == null)
+      {
+         oldRecordMap = new HashMap<>();
+
+         if(oldRecordList != null && updateInput != null)
+         {
+            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/customizers/AbstractPreDeleteCustomizer.java

@@ -0,0 +1,119 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions before a delete takes place.
+ **
+ ** It's important for implementations to be aware of the isPreview field, which
+ ** is set to true when the code is running to give users advice, e.g., on a review
+ ** screen - vs. being false when the action is ACTUALLY happening.  So, if you're doing
+ ** things like storing data, you don't want to do that if isPreview is true!!
+ **
+ ** General implementation would be, to iterate over the records (which the DeleteAction
+ ** would look up based on the inputs to the delete action), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records
+ ** - possibly throwing an exception - if you really don't want the delete operation to continue.
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) - this is how errors
+ **   and warnings are propagated to the DeleteAction.  Note that any records with
+ **   an error will NOT proceed to the backend's delete interface - but those with
+ **   warnings will.
+ **
+ ** Note that the full deleteInput is available as a field in this class.
+ **
+ *******************************************************************************/
+public abstract class AbstractPreDeleteCustomizer
+{
+   protected DeleteInput deleteInput;
+
+   protected boolean isPreview = false;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Getter for deleteInput
+    **
+    *******************************************************************************/
+   public DeleteInput getDeleteInput()
+   {
+      return deleteInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for deleteInput
+    **
+    *******************************************************************************/
+   public void setDeleteInput(DeleteInput deleteInput)
+   {
+      this.deleteInput = deleteInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for isPreview
+    *******************************************************************************/
+   public boolean getIsPreview()
+   {
+      return (this.isPreview);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for isPreview
+    *******************************************************************************/
+   public void setIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for isPreview
+    *******************************************************************************/
+   public AbstractPreDeleteCustomizer withIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+      return (this);
+   }
+
+}

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

@@ -0,0 +1,141 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions before an insert takes place.
+ **
+ ** It's important for implementations to be aware of the isPreview field, which
+ ** is set to true when the code is running to give users advice, e.g., on a review
+ ** screen - vs. being false when the action is ACTUALLY happening.  So, if you're doing
+ ** things like storing data, you don't want to do that if isPreview is true!!
+ **
+ ** General implementation would be, to iterate over the records (the inputs to
+ ** the insert action), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records
+ ** - possibly manipulating values (`setValue`)
+ ** - possibly throwing an exception - if you really don't want the insert operation to continue.
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) that you want to go on to the backend implementation class.
+ **
+ ** Note that the full insertInput is available as a field in this class.
+ *******************************************************************************/
+public abstract class AbstractPreInsertCustomizer
+{
+   protected InsertInput insertInput;
+
+   protected boolean isPreview = false;
+
+
+
+   /////////////////////////////////////////////////////////////////////////////////
+   // allow the customizer to specify when it should be executed as part of the   //
+   // insert action.  default (per method in this class) is AFTER_ALL_VALIDATIONS //
+   /////////////////////////////////////////////////////////////////////////////////
+   public enum WhenToRun
+   {
+      BEFORE_ALL_VALIDATIONS,
+      BEFORE_UNIQUE_KEY_CHECKS,
+      BEFORE_REQUIRED_FIELD_CHECKS,
+      BEFORE_SECURITY_CHECKS,
+      AFTER_ALL_VALIDATIONS
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public WhenToRun getWhenToRun()
+   {
+      return (WhenToRun.AFTER_ALL_VALIDATIONS);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for insertInput
+    **
+    *******************************************************************************/
+   public InsertInput getInsertInput()
+   {
+      return insertInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for insertInput
+    **
+    *******************************************************************************/
+   public void setInsertInput(InsertInput insertInput)
+   {
+      this.insertInput = insertInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for isPreview
+    *******************************************************************************/
+   public boolean getIsPreview()
+   {
+      return (this.isPreview);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for isPreview
+    *******************************************************************************/
+   public void setIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for isPreview
+    *******************************************************************************/
+   public AbstractPreInsertCustomizer withIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+      return (this);
+   }
+
+}

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

@@ -0,0 +1,163 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Abstract class that a table can specify an implementation of, to provide
+ ** custom actions before an update takes place.
+ **
+ ** It's important for implementations to be aware of the isPreview field, which
+ ** is set to true when the code is running to give users advice, e.g., on a review
+ ** screen - vs. being false when the action is ACTUALLY happening.  So, if you're doing
+ ** things like storing data, you don't want to do that if isPreview is true!!
+ **
+ ** General implementation would be, to iterate over the records (the inputs to
+ ** the update action), and look at their values:
+ ** - possibly adding Errors (`addError`) or Warnings (`addWarning`) to the records
+ ** - possibly manipulating values (`setValue`)
+ ** - possibly throwing an exception - if you really don't want the update operation to continue.
+ ** - doing "whatever else" you may want to do.
+ ** - returning the list of records (can be the input list) that you want to go on to the backend implementation class.
+ **
+ ** Note that the full updateInput is available as a field in this class, and the
+ ** "old records" (e.g., with values freshly fetched from the backend) will be
+ ** available (if the backend supports it) - both as a list (`getOldRecordList`)
+ ** and as a memoized (by this class) map of primaryKey to record (`getOldRecordMap`).
+ *******************************************************************************/
+public abstract class AbstractPreUpdateCustomizer
+{
+   protected UpdateInput   updateInput;
+   protected List<QRecord> oldRecordList;
+   protected boolean       isPreview = false;
+
+   private Map<Serializable, QRecord> oldRecordMap = null;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract List<QRecord> apply(List<QRecord> records) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Getter for updateInput
+    **
+    *******************************************************************************/
+   public UpdateInput getUpdateInput()
+   {
+      return updateInput;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for updateInput
+    **
+    *******************************************************************************/
+   public void setUpdateInput(UpdateInput updateInput)
+   {
+      this.updateInput = updateInput;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void setOldRecordList(List<QRecord> oldRecordList)
+   {
+      this.oldRecordList = oldRecordList;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public List<QRecord> getOldRecordList()
+   {
+      return oldRecordList;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   protected Map<Serializable, QRecord> getOldRecordMap()
+   {
+      if(oldRecordMap == null)
+      {
+         oldRecordMap = new HashMap<>();
+         for(QRecord qRecord : oldRecordList)
+         {
+            oldRecordMap.put(qRecord.getValue(updateInput.getTable().getPrimaryKeyField()), qRecord);
+         }
+      }
+
+      return (oldRecordMap);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for isPreview
+    *******************************************************************************/
+   public boolean getIsPreview()
+   {
+      return (this.isPreview);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for isPreview
+    *******************************************************************************/
+   public void setIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for isPreview
+    *******************************************************************************/
+   public AbstractPreUpdateCustomizer withIsPreview(boolean isPreview)
+   {
+      this.isPreview = isPreview;
+      return (this);
+   }
+
+}

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

@@ -0,0 +1,232 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QRuntimeException;
+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.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.statusmessages.QStatusMessage;
+import com.kingsrook.qqq.backend.core.model.statusmessages.QWarningMessage;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+
+
+/*******************************************************************************
+ ** Standard/re-usable post-insert customizer, for the use case where, when we
+ ** do an insert into table "parent", we want a record automatically inserted into
+ ** table "child".  Optionally (based on RelationshipType), there can be a foreign
+ ** key in "parent", pointed at "child".  e.g., named: "parent.childId".
+ **
+ *******************************************************************************/
+public abstract class ChildInserterPostInsertCustomizer extends AbstractPostInsertCustomizer
+{
+   public enum RelationshipType
+   {
+      PARENT_POINTS_AT_CHILD,
+      CHILD_POINTS_AT_PARENT
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract QRecord buildChildForRecord(QRecord parentRecord) throws QException;
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract String getChildTableName();
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String getForeignKeyFieldName()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public abstract RelationshipType getRelationshipType();
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public List<QRecord> apply(List<QRecord> records)
+   {
+      try
+      {
+         List<QRecord>  rs               = records;
+         List<QRecord>  childrenToInsert = new ArrayList<>();
+         QTableMetaData table            = getInsertInput().getTable();
+         QTableMetaData childTable       = getInsertInput().getInstance().getTable(getChildTableName());
+
+         ////////////////////////////////////////////////////////////////////////////////
+         // iterate over the inserted records, building a list child records to insert //
+         // for ones missing a value in the foreign key field.                         //
+         ////////////////////////////////////////////////////////////////////////////////
+         switch(getRelationshipType())
+         {
+            case PARENT_POINTS_AT_CHILD ->
+            {
+               String foreignKeyFieldName = getForeignKeyFieldName();
+               try
+               {
+                  table.getField(foreignKeyFieldName);
+               }
+               catch(Exception e)
+               {
+                  throw new QRuntimeException("For RelationshipType.PARENT_POINTS_AT_CHILD, a valid foreignKeyFieldName in the parent table must be given.  "
+                     + "[" + foreignKeyFieldName + "] is not a valid field name in table [" + table.getName() + "]");
+               }
+
+               for(QRecord record : records)
+               {
+                  if(record.getValue(foreignKeyFieldName) == null)
+                  {
+                     childrenToInsert.add(buildChildForRecord(record));
+                  }
+               }
+            }
+            case CHILD_POINTS_AT_PARENT ->
+            {
+               for(QRecord record : records)
+               {
+                  childrenToInsert.add(buildChildForRecord(record));
+               }
+            }
+            default -> throw new IllegalStateException("Unexpected value: " + getRelationshipType());
+         }
+
+         ///////////////////////////////////////////////////////////////////////////////////
+         // if there are no children to insert, then just return the original record list //
+         ///////////////////////////////////////////////////////////////////////////////////
+         if(childrenToInsert.isEmpty())
+         {
+            return (records);
+         }
+
+         /////////////////////////
+         // insert the children //
+         /////////////////////////
+         InsertInput insertInput = new InsertInput();
+         insertInput.setTableName(getChildTableName());
+         insertInput.setRecords(childrenToInsert);
+         insertInput.setTransaction(this.insertInput.getTransaction());
+         InsertOutput      insertOutput           = new InsertAction().execute(insertInput);
+         Iterator<QRecord> insertedRecordIterator = insertOutput.getRecords().iterator();
+
+         /////////////////////////////////////////////////////////////////////////////////
+         // check for any errors when inserting the children, if any errors were found, //
+         // then set a warning in the parent with the details of the problem            //
+         /////////////////////////////////////////////////////////////////////////////////
+
+         //////////////////////////////////////////////////////////////////////////////////////////////////////
+         // for the PARENT_POINTS_AT_CHILD relationship type:
+         // iterate over the original list of records again - for any that need a child (e.g., are missing   //
+         // foreign key), set their foreign key to a newly inserted child's key, and add them to be updated. //
+         //////////////////////////////////////////////////////////////////////////////////////////////////////
+         switch(getRelationshipType())
+         {
+            case PARENT_POINTS_AT_CHILD ->
+            {
+               rs = new ArrayList<>();
+               List<QRecord> recordsToUpdate = new ArrayList<>();
+               for(QRecord record : records)
+               {
+                  Serializable primaryKey = record.getValue(table.getPrimaryKeyField());
+                  if(record.getValue(getForeignKeyFieldName()) == null)
+                  {
+                     ///////////////////////////////////////////////////////////////////////////////////////////////////
+                     // get the corresponding child record, if it has any errors, set that as a warning in the parent //
+                     ///////////////////////////////////////////////////////////////////////////////////////////////////
+                     QRecord childRecord = insertedRecordIterator.next();
+                     if(CollectionUtils.nullSafeHasContents(childRecord.getErrors()))
+                     {
+                        for(QStatusMessage error : childRecord.getErrors())
+                        {
+                           record.addWarning(new QWarningMessage("Error creating child " + childTable.getLabel() + " (" + error.toString() + ")"));
+                        }
+                        rs.add(record);
+                        continue;
+                     }
+
+                     Serializable foreignKey = childRecord.getValue(childTable.getPrimaryKeyField());
+                     recordsToUpdate.add(new QRecord().withValue(table.getPrimaryKeyField(), primaryKey).withValue(getForeignKeyFieldName(), foreignKey));
+                     record.setValue(getForeignKeyFieldName(), foreignKey);
+                     rs.add(record);
+                  }
+                  else
+                  {
+                     rs.add(record);
+                  }
+               }
+
+               ////////////////////////////////////////////////////////////////////////////
+               // update the originally inserted records to reference their new children //
+               ////////////////////////////////////////////////////////////////////////////
+               UpdateInput updateInput = new UpdateInput();
+               updateInput.setTableName(getInsertInput().getTableName());
+               updateInput.setRecords(recordsToUpdate);
+               updateInput.setTransaction(this.insertInput.getTransaction());
+               new UpdateAction().execute(updateInput);
+            }
+            case CHILD_POINTS_AT_PARENT ->
+            {
+               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+               // todo - some version of looking at the inserted children to confirm that they were inserted, and updating the parents with warnings if they weren't //
+               ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            }
+            default -> throw new IllegalStateException("Unexpected value: " + getRelationshipType());
+         }
+
+         return (rs);
+      }
+      catch(RuntimeException re)
+      {
+         throw (re);
+      }
+      catch(Exception e)
+      {
+         throw new RuntimeException("Error inserting new child records for new parent records", e);
+      }
+   }
+}

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

@@ -28,13 +28,13 @@ import com.kingsrook.qqq.backend.core.actions.automation.RecordAutomationHandler
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
 import com.kingsrook.qqq.backend.core.actions.values.QCustomPossibleValueProvider;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeType;
 import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.automation.TableAutomationAction;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -42,7 +42,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class QCodeLoader
 {
-   private static final Logger LOG = LogManager.getLogger(QCodeLoader.class);
+   private static final QLogger LOG = QLogger.getLogger(QCodeLoader.class);
 
 
 
@@ -61,6 +61,21 @@ public class QCodeLoader
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static <T> Optional<T> getTableCustomizer(Class<T> expectedClass, QTableMetaData table, String customizerName)
+   {
+      Optional<QCodeReference> codeReference = table.getCustomizer(customizerName);
+      if(codeReference.isPresent())
+      {
+         return (Optional.ofNullable(QCodeLoader.getAdHoc(expectedClass, codeReference.get())));
+      }
+      return (Optional.empty());
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -87,7 +102,7 @@ public class QCodeLoader
       }
       catch(Exception e)
       {
-         LOG.error("Error initializing customizer: " + codeReference);
+         LOG.error("Error initializing customizer", logPair("codeReference", codeReference), e);
 
          //////////////////////////////////////////////////////////////////////////////////////////////////////////
          // return null here - under the assumption that during normal run-time operations, we'll never hit here //
@@ -126,7 +141,7 @@ public class QCodeLoader
       }
       catch(Exception e)
       {
-         LOG.error("Error initializing customizer: " + codeReference);
+         LOG.error("Error initializing customizer", logPair("codeReference", codeReference), e);
 
          //////////////////////////////////////////////////////////////////////////////////////////////////////////
          // return null here - under the assumption that during normal run-time operations, we'll never hit here //
@@ -165,7 +180,7 @@ public class QCodeLoader
       }
       catch(Exception e)
       {
-         LOG.error("Error initializing customizer: " + codeReference);
+         LOG.error("Error initializing customizer", logPair("codeReference", codeReference), e);
 
          //////////////////////////////////////////////////////////////////////////////////////////////////////////
          // return null here - under the assumption that during normal run-time operations, we'll never hit here //

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

@@ -0,0 +1,149 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.customizers;
+
+
+import java.io.Serializable;
+import java.util.HashMap;
+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.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.statusmessages.BadInputStatusMessage;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Interface with utility methods that pre insert/update/delete customizers
+ ** may want to use.
+ *******************************************************************************/
+public interface RecordCustomizerUtilityInterface
+{
+   QLogger LOG = QLogger.getLogger(RecordCustomizerUtilityInterface.class);
+
+
+
+   /*******************************************************************************
+    ** Container for an old value and a new value.
+    *******************************************************************************/
+   @SuppressWarnings("checkstyle:MethodName")
+   record Change(Serializable oldValue, Serializable newValue)
+   {
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default Map<String, Change> getChanges(String tableName, QRecord oldRecord, QRecord newRecord)
+   {
+      Map<String, Change> rs = new HashMap<>();
+
+      QTableMetaData table = QContext.getQInstance().getTable(tableName);
+      for(Map.Entry<String, Serializable> entry : newRecord.getValues().entrySet())
+      {
+         String       fieldName = entry.getKey();
+         Serializable newValue  = entry.getValue();
+         Serializable oldValue  = oldRecord.getValue(fieldName);
+
+         try
+         {
+            QFieldMetaData field         = table.getField(fieldName);
+            Serializable   newTypedValue = ValueUtils.getValueAsFieldType(field.getType(), newValue);
+            Serializable   oldTypedValue = ValueUtils.getValueAsFieldType(field.getType(), oldValue);
+
+            if(!Objects.equals(oldTypedValue, newTypedValue))
+            {
+               rs.put(fieldName, new Change(oldTypedValue, newTypedValue));
+            }
+         }
+         catch(Exception e)
+         {
+            LOG.info("Error getting a value as field's type", e, logPair("fieldName", fieldName), logPair("oldValue", oldValue), logPair("newValue", newValue));
+         }
+      }
+
+      return (rs);
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void errorIfNoValue(Serializable value, QRecord record, String errorMessage)
+   {
+      errorIf(!StringUtils.hasContent(ValueUtils.getValueAsString(value)), record, errorMessage);
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void errorIfEditedValue(QRecord oldRecord, QRecord newRecord, String fieldName, String errorMessage)
+   {
+      if(newRecord.getValues().containsKey(fieldName))
+      {
+         errorIf(isChangedValue(oldRecord.getValue(fieldName), newRecord.getValue(fieldName)), newRecord, errorMessage);
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default boolean isChangedValue(Serializable oldValue, Serializable newValue)
+   {
+      //////////////////////////////////////////////
+      // todo - probably ... some type "coercion" //
+      //////////////////////////////////////////////
+      return (!Objects.equals(oldValue, newValue));
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void errorIfAnyValue(Serializable value, QRecord record, String errorMessage)
+   {
+      if(StringUtils.hasContent(ValueUtils.getValueAsString(value)))
+      {
+         record.addError(new BadInputStatusMessage(errorMessage));
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void errorIf(boolean condition, QRecord record, String errorMessage)
+   {
+      if(condition)
+      {
+         record.addError(new BadInputStatusMessage(errorMessage));
+      }
+   }
+
+}

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

@@ -22,45 +22,34 @@
 package com.kingsrook.qqq.backend.core.actions.customizers;
 
 
-import java.util.function.Function;
-import com.kingsrook.qqq.backend.core.model.data.QRecord;
-
-
 /*******************************************************************************
  ** Enum definition of possible table customizers - "roles" for custom code that
  ** can be applied to tables.
  **
- ** Works with TableCustomizer (singular version of this name) objects, during
- ** instance validation, to provide validation of the referenced code (and to
- ** make such validation from sub-backend-modules possible in the future).
- **
- ** The idea of the 3rd argument here is to provide a way that we can enforce
- ** the type-parameters for the custom code.  E.g., if it's a Function - how
- ** can we check at run-time that the type-params are correct?  We couldn't find
- ** how to do this "reflectively", so we can instead try to run the custom code,
- ** passing it objects of the type that this customizer expects, and a validation
- ** error will raise upon ClassCastException...  This maybe could improve!
  *******************************************************************************/
 public enum TableCustomizers
 {
-   POST_QUERY_RECORD(new TableCustomizer("postQueryRecord", Function.class, ((Object x) ->
-   {
-      @SuppressWarnings("unchecked")
-      Function<QRecord, QRecord> function = (Function<QRecord, QRecord>) x;
-      QRecord                    output   = function.apply(new QRecord());
-   })));
+   POST_QUERY_RECORD("postQueryRecord", AbstractPostQueryCustomizer.class),
+   PRE_INSERT_RECORD("preInsertRecord", AbstractPreInsertCustomizer.class),
+   POST_INSERT_RECORD("postInsertRecord", AbstractPostInsertCustomizer.class),
+   PRE_UPDATE_RECORD("preUpdateRecord", AbstractPreUpdateCustomizer.class),
+   POST_UPDATE_RECORD("postUpdateRecord", AbstractPostUpdateCustomizer.class),
+   PRE_DELETE_RECORD("preDeleteRecord", AbstractPreDeleteCustomizer.class),
+   POST_DELETE_RECORD("postDeleteRecord", AbstractPostDeleteCustomizer.class);
 
 
-   private final TableCustomizer tableCustomizer;
+   private final String   role;
+   private final Class<?> expectedType;
 
 
 
    /*******************************************************************************
     **
     *******************************************************************************/
-   TableCustomizers(TableCustomizer tableCustomizer)
+   TableCustomizers(String role, Class<?> expectedType)
    {
-      this.tableCustomizer = tableCustomizer;
+      this.role = role;
+      this.expectedType = expectedType;
    }
 
 
@@ -73,7 +62,7 @@ public enum TableCustomizers
    {
       for(TableCustomizers value : values())
       {
-         if(value.tableCustomizer.getRole().equals(name))
+         if(value.role.equals(name))
          {
             return (value);
          }
@@ -84,24 +73,23 @@ public enum TableCustomizers
 
 
 
-   /*******************************************************************************
-    ** Getter for tableCustomizer
-    **
-    *******************************************************************************/
-   public TableCustomizer getTableCustomizer()
-   {
-      return tableCustomizer;
-   }
-
-
-
    /*******************************************************************************
     ** get the role from the tableCustomizer
     **
     *******************************************************************************/
    public String getRole()
    {
-      return (tableCustomizer.getRole());
+      return (role);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for expectedType
+    **
+    *******************************************************************************/
+   public Class<?> getExpectedType()
+   {
+      return expectedType;
+   }
 }

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

@@ -25,13 +25,23 @@ package com.kingsrook.qqq.backend.core.actions.dashboard;
 import java.io.Serializable;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.DisplayFormat;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
 
 /*******************************************************************************
@@ -45,10 +55,10 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
-   protected String openTopLevelBulletList()
+   public static String openTopLevelBulletList()
    {
       return ("""
-         <div style="padding: 1rem;">
+         <div style="padding-left: 2rem;">
             <ul>""");
    }
 
@@ -57,7 +67,7 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
-   protected String closeTopLevelBulletList()
+   public static String closeTopLevelBulletList()
    {
       return ("""
             </ul>
@@ -101,7 +111,7 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
     *******************************************************************************/
    protected String bulletNameValue(String name, String value)
    {
-      return ("<li><b>" + name + "</b> &nbsp; " + value + "</li>");
+      return ("<li><b>" + name + "</b> &nbsp; " + Objects.requireNonNullElse(value, "--") + "</li>");
    }
 
 
@@ -111,7 +121,7 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
     *******************************************************************************/
    public static String linkTableBulkLoad(RenderWidgetInput input, String tableName) throws QException
    {
-      String tablePath = input.getInstance().getTablePath(input, tableName);
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
       return (tablePath + "/" + tableName + ".bulkInsert");
    }
 
@@ -120,34 +130,293 @@ public abstract class AbstractHTMLWidgetRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
-   public static String linkTableFilter(RenderWidgetInput input, String tableName, QQueryFilter filter) throws QException
+   public static String linkTableBulkLoadChildren(RenderWidgetInput input, String tableName) throws QException
    {
-      String tablePath = input.getInstance().getTablePath(input, tableName);
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
+      return ("#/launchProcess=" + tableName + ".bulkInsert");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableCreate(RenderWidgetInput input, String tableName) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      return (tablePath + "/create");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableCreateWithDefaultValues(RenderWidgetInput input, String tableName, Map<String, Serializable> defaultValues) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      return (tablePath + "/create?defaultValues=" + URLEncoder.encode(JsonUtils.toJson(defaultValues), Charset.defaultCharset()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String getCountLink(RenderWidgetInput input, String tableName, QQueryFilter filter, int count) throws QException
+   {
+      String totalString = QValueFormatter.formatValue(DisplayFormat.COMMAS, count);
+      String tablePath   = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null || filter == null)
+      {
+         return (totalString);
+      }
+      return ("<a href='" + tablePath + "?filter=" + JsonUtils.toJson(filter) + "'>" + totalString + "</a>");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void addTableFilterToListIfPermissed(RenderWidgetInput input, String tableName, List<String> urls, QQueryFilter filter) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return;
+      }
+
+      urls.add(tablePath + "?filter=" + JsonUtils.toJson(filter));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableFilterUnencoded(RenderWidgetInput input, String tableName, QQueryFilter filter) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
+      return (tablePath + "?filter=" + JsonUtils.toJson(filter));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableFilter(String tableName, QQueryFilter filter) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
       return (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset()));
    }
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String aHrefTableFilterNoOfRecords(String tableName, QQueryFilter filter, Integer noOfRecords, String singularLabel, String pluralLabel) throws QException
+   {
+      return (aHrefTableFilterNoOfRecords(tableName, filter, noOfRecords, singularLabel, pluralLabel, false));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String aHrefTableFilterNoOfRecords(String tableName, QQueryFilter filter, Integer noOfRecords, String singularLabel, String pluralLabel, boolean onlyLinkCount) throws QException
+   {
+      String plural      = StringUtils.plural(noOfRecords, singularLabel, pluralLabel);
+      String countString = QValueFormatter.formatValue(DisplayFormat.COMMAS, noOfRecords);
+      String displayText = StringUtils.hasContent(plural) ? (" " + plural) : "";
+      String tablePath   = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (countString + displayText);
+      }
+
+      String href = linkTableFilter(tableName, filter);
+      if(onlyLinkCount)
+      {
+         return ("<a href=\"" + href + "\">" + countString + "</a>" + displayText);
+      }
+      else
+      {
+         return ("<a href=\"" + href + "\">" + countString + displayText + "</a>");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String aHrefViewRecord(String tableName, Serializable id, String linkText) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (linkText);
+      }
+
+      return ("<a href=\"" + linkRecordView(tableName, id) + "\">" + linkText + "</a>");
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    public static String linkRecordEdit(AbstractActionInput input, String tableName, Serializable recordId) throws QException
    {
-      String tablePath = input.getInstance().getTablePath(input, tableName);
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
       return (tablePath + "/" + recordId + "/edit");
    }
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkRecordView(String tableName, Serializable recordId) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
+      return (tablePath + "/" + recordId);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkProcessForFilter(AbstractActionInput input, String processName, QQueryFilter filter) throws QException
+   {
+      QProcessMetaData process = QContext.getQInstance().getProcess(processName);
+      if(process == null)
+      {
+         return (null);
+      }
+      String tableName = process.getTableName();
+      if(tableName == null)
+      {
+         return (null);
+      }
+
+      String tablePath = QContext.getQInstance().getTablePath(tableName);
+      return (tablePath + "/" + processName + "?recordsParam=filterJSON&filterJSON=" + URLEncoder.encode(JsonUtils.toJson(filter), StandardCharsets.UTF_8));
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    public static String linkProcessForRecord(AbstractActionInput input, String processName, Serializable recordId) throws QException
    {
-      QProcessMetaData process   = input.getInstance().getProcess(processName);
+      QProcessMetaData process   = QContext.getQInstance().getProcess(processName);
       String           tableName = process.getTableName();
-      String           tablePath = input.getInstance().getTablePath(input, tableName);
+      String           tablePath = QContext.getQInstance().getTablePath(tableName);
+
       return (tablePath + "/" + recordId + "/" + processName);
    }
 
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableCreateChild(RenderWidgetInput input, String childTableName, Map<String, Serializable> defaultValues) throws QException
+   {
+      return (linkTableCreateChild(input, childTableName, defaultValues, defaultValues.keySet()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String aHrefTableCreateChild(RenderWidgetInput input, String childTableName, Map<String, Serializable> defaultValues) throws QException
+   {
+      return (aHrefTableCreateChild(input, childTableName, defaultValues, defaultValues.keySet()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String linkTableCreateChild(RenderWidgetInput input, String childTableName, Map<String, Serializable> defaultValues, Set<String> disabledFields) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(childTableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
+      Map<String, Integer> disabledFieldsMap = disabledFields.stream().collect(Collectors.toMap(k -> k, k -> 1));
+
+      return ("#/createChild=" + childTableName
+         + "/defaultValues=" + URLEncoder.encode(JsonUtils.toJson(defaultValues), StandardCharsets.UTF_8).replaceAll("\\+", "%20")
+         + "/disabledFields=" + URLEncoder.encode(JsonUtils.toJson(disabledFieldsMap), StandardCharsets.UTF_8).replaceAll("\\+", "%20"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String getChipElement(String icon, String label, String color) throws QException
+   {
+      color = color != null ? color : "info";
+      color = StringUtils.ucFirst(color);
+
+      String html = "<span style='display: flex;'>";
+      html += "<div style='overflow: hidden; flex: none; display: flex; align-content: flex-start; align-items: center; height: 24px; padding-right: 8px; font-size: 13px; font-weight: 500; border: 1px solid; border-radius: 16px; color: " + color + "'>";
+      if(icon != null)
+      {
+         html += "<span style='font-size: 16px; padding: 5px' class='material-icons-round notranslate MuiIcon-root MuiIcon-fontSizeInherit MuiChip-icon MuiChip-iconSmall MuiChip-iconColor" + color + "'>" + icon + "</span>";
+      }
+      html += "<span class='MuiChip-label MuiChip-labelSmall'>" + label + "</span></div></span>";
+      return (html);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String aHrefTableCreateChild(RenderWidgetInput input, String childTableName, Map<String, Serializable> defaultValues, Set<String> disabledFields) throws QException
+   {
+      String tablePath = QContext.getQInstance().getTablePath(childTableName);
+      if(tablePath == null)
+      {
+         return (null);
+      }
+
+      return ("<a href=\"" + linkTableCreateChild(input, childTableName, defaultValues, defaultValues.keySet()) + "\">Create new</a>");
+   }
+
 }

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

@@ -30,7 +30,6 @@ import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRe
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 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.metadata.dashboard.QWidgetMetaData;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 
 
@@ -53,12 +52,9 @@ public class RenderWidgetAction
       ///////////////////////////////////////////////////////////////
       // move default values from meta data into this render input //
       ///////////////////////////////////////////////////////////////
-      if(input.getWidgetMetaData() instanceof QWidgetMetaData widgetMetaData)
+      for(Map.Entry<String, Serializable> entry : input.getWidgetMetaData().getDefaultValues().entrySet())
       {
-         for(Map.Entry<String, Serializable> entry : widgetMetaData.getDefaultValues().entrySet())
-         {
-            input.addQueryParam(entry.getKey(), ValueUtils.getValueAsString(entry.getValue()));
-         }
+         input.addQueryParam(entry.getKey(), ValueUtils.getValueAsString(entry.getValue()));
       }
 
       return (widgetRenderer.render(input));

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

@@ -24,10 +24,29 @@ package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 import java.time.ZoneId;
 import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
+import com.kingsrook.qqq.backend.core.actions.values.SearchPossibleValueSourceAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceInput;
+import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceOutput;
 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.QWidgetData;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.WidgetDropdownData;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.collections.MapBuilder;
 
 
 /*******************************************************************************
@@ -46,4 +65,101 @@ public abstract class AbstractWidgetRenderer
     *******************************************************************************/
    public abstract RenderWidgetOutput render(RenderWidgetInput input) throws QException;
 
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   protected boolean setupDropdowns(RenderWidgetInput input, QWidgetMetaData metaData, QWidgetData widgetData) throws QException
+   {
+      List<List<Map<String, String>>> pvsData                   = new ArrayList<>();
+      List<String>                    pvsLabels                 = new ArrayList<>();
+      List<String>                    pvsNames                  = new ArrayList<>();
+      List<String>                    missingRequiredSelections = new ArrayList<>();
+      for(WidgetDropdownData dropdownData : CollectionUtils.nonNullList(metaData.getDropdowns()))
+      {
+         String               possibleValueSourceName = dropdownData.getPossibleValueSourceName();
+         QPossibleValueSource possibleValueSource     = input.getInstance().getPossibleValueSource(possibleValueSourceName);
+
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // this looks complicated, but is just look for a label in the dropdown data and if found use it,                                                                                  //
+         // otherwise look for label in PVS and if found use that, otherwise just use the PVS name                                                                                          //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         String pvsLabel = dropdownData.getLabel() != null ? dropdownData.getLabel() : (possibleValueSource.getLabel() != null ? possibleValueSource.getLabel() : possibleValueSourceName);
+         pvsLabels.add(pvsLabel);
+         pvsNames.add(possibleValueSourceName);
+
+         SearchPossibleValueSourceInput pvsInput = new SearchPossibleValueSourceInput();
+         pvsInput.setPossibleValueSourceName(possibleValueSourceName);
+
+         if(dropdownData.getForeignKeyFieldName() != null)
+         {
+            ////////////////////////////////////////
+            // look for an id in the query params //
+            ////////////////////////////////////////
+            Integer id = null;
+            if(input.getQueryParams() != null && input.getQueryParams().containsKey("id") && StringUtils.hasContent(input.getQueryParams().get("id")))
+            {
+               id = Integer.parseInt(input.getQueryParams().get("id"));
+            }
+            if(id != null)
+            {
+               pvsInput.setDefaultQueryFilter(new QQueryFilter().withCriteria(
+                  new QFilterCriteria(
+                     dropdownData.getForeignKeyFieldName(),
+                     QCriteriaOperator.EQUALS,
+                     id)));
+            }
+         }
+
+         SearchPossibleValueSourceOutput output = new SearchPossibleValueSourceAction().execute(pvsInput);
+
+         List<Map<String, String>> dropdownOptionList = new ArrayList<>();
+         pvsData.add(dropdownOptionList);
+
+         //////////////////////////////////////////
+         // sort results, dedupe, and add to map //
+         //////////////////////////////////////////
+         Set<String> exists = new HashSet<>();
+         output.getResults().removeIf(pvs -> !exists.add(pvs.getLabel()));
+         for(QPossibleValue<?> possibleValue : output.getResults())
+         {
+            dropdownOptionList.add(MapBuilder.of(
+               "id", String.valueOf(possibleValue.getId()),
+               "label", possibleValue.getLabel()
+            ));
+         }
+
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // because we know the dropdowns and what the field names will be when something is selected, we can make //
+         // sure that something has been selected, and if not, display a message that a selection needs made       //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         if(dropdownData.getIsRequired())
+         {
+            if(!input.getQueryParams().containsKey(possibleValueSourceName) || !StringUtils.hasContent(input.getQueryParams().get(possibleValueSourceName)))
+            {
+               missingRequiredSelections.add(pvsLabel);
+            }
+         }
+      }
+
+      widgetData.setDropdownNameList(pvsNames);
+      widgetData.setDropdownLabelList(pvsLabels);
+      widgetData.setDropdownDataList(pvsData);
+
+      ////////////////////////////////////////////////////////////////////////////////
+      // if there are any missing required dropdowns, build up a message to display //
+      ////////////////////////////////////////////////////////////////////////////////
+      if(missingRequiredSelections.size() > 0)
+      {
+         StringBuilder sb = new StringBuilder("Please select a ").append(StringUtils.joinWithCommasAndAnd(missingRequiredSelections));
+         sb.append(" from the ").append(StringUtils.plural(missingRequiredSelections.size(), "dropdown", "dropdowns")).append(" above.");
+         widgetData.setDropdownNeedsSelectedText(sb.toString());
+         return (false);
+      }
+      else
+      {
+         return (true);
+      }
+   }
 }

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

@@ -22,13 +22,21 @@
 package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 
+import java.io.Serializable;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
+import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QNotFoundException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
@@ -42,11 +50,15 @@ import com.kingsrook.qqq.backend.core.model.dashboard.widgets.ChildRecordListDat
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.AbstractWidgetMetaDataBuilder;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 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 org.apache.commons.lang.BooleanUtils;
 
 
 /*******************************************************************************
@@ -58,13 +70,87 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
    /*******************************************************************************
     **
     *******************************************************************************/
-   public static QWidgetMetaData defineWidgetFromJoin(QJoinMetaData join)
+   public static Builder widgetMetaDataBuilder(QJoinMetaData join)
    {
-      return (new QWidgetMetaData()
+      return (new Builder(new QWidgetMetaData()
          .withName(join.getName())
-         .withCodeReference(new QCodeReference(ChildRecordListRenderer.class, null))
+         .withIsCard(true)
+         .withCodeReference(new QCodeReference(ChildRecordListRenderer.class))
          .withType(WidgetType.CHILD_RECORD_LIST.getType())
-         .withDefaultValue("joinName", join.getName()));
+         .withDefaultValue("joinName", join.getName())));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static class Builder extends AbstractWidgetMetaDataBuilder
+   {
+
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      public Builder(QWidgetMetaData widgetMetaData)
+      {
+         super(widgetMetaData);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withName(String name)
+      {
+         widgetMetaData.setName(name);
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withLabel(String label)
+      {
+         widgetMetaData.setLabel(label);
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withMaxRows(Integer maxRows)
+      {
+         widgetMetaData.withDefaultValue("maxRows", maxRows);
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withCanAddChildRecord(boolean b)
+      {
+         widgetMetaData.withDefaultValue("canAddChildRecord", true);
+         return (this);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public Builder withDisabledFieldsForNewChildRecords(Set<String> disabledFieldsForNewChildRecords)
+      {
+         widgetMetaData.withDefaultValue("disabledFieldsForNewChildRecords", new HashSet<>(disabledFieldsForNewChildRecords));
+         return (this);
+      }
    }
 
 
@@ -75,17 +161,28 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
    @Override
    public RenderWidgetOutput render(RenderWidgetInput input) throws QException
    {
-      String        widgetLabel = input.getQueryParams().get("widgetLabel");
-      String        joinName    = input.getQueryParams().get("joinName");
-      QJoinMetaData join        = input.getInstance().getJoin(joinName);
-      String        id          = input.getQueryParams().get("id");
+      String         widgetLabel = input.getQueryParams().get("widgetLabel");
+      String         joinName    = input.getQueryParams().get("joinName");
+      QJoinMetaData  join        = input.getInstance().getJoin(joinName);
+      String         id          = input.getQueryParams().get("id");
+      QTableMetaData leftTable   = input.getInstance().getTable(join.getLeftTable());
+      QTableMetaData rightTable  = input.getInstance().getTable(join.getRightTable());
+
+      Integer maxRows = null;
+      if(StringUtils.hasContent(input.getQueryParams().get("maxRows")))
+      {
+         maxRows = ValueUtils.getValueAsInteger(input.getQueryParams().get("maxRows"));
+      }
+      else if(input.getWidgetMetaData().getDefaultValues().containsKey("maxRows"))
+      {
+         maxRows = ValueUtils.getValueAsInteger(input.getWidgetMetaData().getDefaultValues().containsKey("maxRows"));
+      }
 
       ////////////////////////////////////////////////////////
       // fetch the record that we're getting children for.  //
       // e.g., the left-side of the join, with the input id //
       ////////////////////////////////////////////////////////
-      GetInput getInput = new GetInput(input.getInstance());
-      getInput.setSession(input.getSession());
+      GetInput getInput = new GetInput();
       getInput.setTableName(join.getLeftTable());
       getInput.setPrimaryKey(id);
       GetOutput getOutput = new GetAction().execute(getInput);
@@ -93,8 +190,7 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
 
       if(record == null)
       {
-         QTableMetaData table = input.getInstance().getTable(join.getLeftTable());
-         throw (new QNotFoundException("Could not find " + (table == null ? "" : table.getLabel()) + " with primary key " + id));
+         throw (new QNotFoundException("Could not find " + (leftTable == null ? "" : leftTable.getLabel()) + " with primary key " + id));
       }
 
       ////////////////////////////////////////////////////////////////////
@@ -106,20 +202,57 @@ public class ChildRecordListRenderer extends AbstractWidgetRenderer
          filter.addCriteria(new QFilterCriteria(joinOn.getRightField(), QCriteriaOperator.EQUALS, List.of(record.getValue(joinOn.getLeftField()))));
       }
       filter.setOrderBys(join.getOrderBys());
+      filter.setLimit(maxRows);
 
-      QueryInput queryInput = new QueryInput(input.getInstance());
-      queryInput.setSession(input.getSession());
+      QueryInput queryInput = new QueryInput();
       queryInput.setTableName(join.getRightTable());
       queryInput.setShouldTranslatePossibleValues(true);
       queryInput.setShouldGenerateDisplayValues(true);
       queryInput.setFilter(filter);
       QueryOutput queryOutput = new QueryAction().execute(queryInput);
 
-      QTableMetaData table       = input.getInstance().getTable(join.getRightTable());
-      String         tablePath   = input.getInstance().getTablePath(input, table.getName());
-      String         viewAllLink = tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset());
+      QValueFormatter.setBlobValuesToDownloadUrls(rightTable, queryOutput.getRecords());
 
-      return (new RenderWidgetOutput(new ChildRecordListData(widgetLabel, queryOutput, table, tablePath, viewAllLink)));
+      int totalRows = queryOutput.getRecords().size();
+      if(maxRows != null && (queryOutput.getRecords().size() == maxRows))
+      {
+         /////////////////////////////////////////////////////////////////////////////////////
+         // if the input said to only do some max, and the # of results we got is that max, //
+         // then do a count query, for displaying 1-n of <count>                            //
+         /////////////////////////////////////////////////////////////////////////////////////
+         CountInput countInput = new CountInput();
+         countInput.setTableName(join.getRightTable());
+         countInput.setFilter(filter);
+         totalRows = new CountAction().execute(countInput).getCount();
+      }
+
+      String tablePath   = input.getInstance().getTablePath(rightTable.getName());
+      String viewAllLink = tablePath == null ? null : (tablePath + "?filter=" + URLEncoder.encode(JsonUtils.toJson(filter), Charset.defaultCharset()));
+
+      ChildRecordListData widgetData = new ChildRecordListData(widgetLabel, queryOutput, rightTable, tablePath, viewAllLink, totalRows);
+
+      if(BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(input.getQueryParams().get("canAddChildRecord"))))
+      {
+         widgetData.setCanAddChildRecord(true);
+
+         //////////////////////////////////////////////////////////
+         // new child records must have values from the join-ons //
+         //////////////////////////////////////////////////////////
+         Map<String, Serializable> defaultValuesForNewChildRecords = new HashMap<>();
+         for(JoinOn joinOn : join.getJoinOns())
+         {
+            defaultValuesForNewChildRecords.put(joinOn.getRightField(), record.getValue(joinOn.getLeftField()));
+         }
+         widgetData.setDefaultValuesForNewChildRecords(defaultValuesForNewChildRecords);
+
+         Map<String, Serializable> widgetValues = input.getWidgetMetaData().getDefaultValues();
+         if(widgetValues.containsKey("disabledFieldsForNewChildRecords"))
+         {
+            widgetData.setDisabledFieldsForNewChildRecords((Set<String>) widgetValues.get("disabledFieldsForNewChildRecords"));
+         }
+      }
+
+      return (new RenderWidgetOutput(widgetData));
    }
 
 }

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

@@ -0,0 +1,300 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import java.time.DayOfWeek;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.temporal.ChronoField;
+import java.time.temporal.ChronoUnit;
+import java.time.temporal.IsoFields;
+import java.time.temporal.TemporalAdjusters;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** Enum to define various "levels" of group-by for on dashboards that want to
+ ** group records by, e.g., year, or month, or week, or day, or hour.
+ *******************************************************************************/
+public enum DateTimeGroupBy
+{
+   /////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   // note - double %'s on the time format strings here, because this is a java-format string, which will get //
+   // its '%s' replaced with a column name, and so then those %'s for the date_format need escaped as %%.     //
+   // See https://www.w3schools.com/sql/func_mysql_date_format.asp for DATE_FORMAT args                       //
+   /////////////////////////////////////////////////////////////////////////////////////////////////////////////
+   YEAR("%%Y", MillisPer.YEAR, 1, ChronoUnit.YEARS, DateTimeFormatter.ofPattern("yyyy"), DateTimeFormatter.ofPattern("yyyy")),
+   MONTH("%%Y-%%m", 2 * MillisPer.MONTH, 1, ChronoUnit.MONTHS, DateTimeFormatter.ofPattern("yyyy-MM"), DateTimeFormatter.ofPattern("MMM'.' yyyy")),
+   WEEK("%%XW%%V", 35 * MillisPer.DAY, 7, ChronoUnit.DAYS, DateTimeFormatter.ofPattern("YYYY'W'ww"), DateTimeFormatter.ofPattern("YYYY'W'w")),
+   DAY("%%Y-%%m-%%d", 36 * MillisPer.HOUR, 1, ChronoUnit.DAYS, DateTimeFormatter.ofPattern("yyyy-MM-dd"), DateTimeFormatter.ofPattern("EEE'.' M'/'d")),
+   HOUR("%%Y-%%m-%%dT%%H", 0, 1, ChronoUnit.HOURS, DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH"), DateTimeFormatter.ofPattern("h a"));
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public interface MillisPer
+   {
+      long HOUR  = 60 * 60 * 1000;
+      long DAY   = 24 * HOUR;
+      long WEEK  = 7 * DAY;
+      long MONTH = 30 * DAY;
+      long YEAR  = 365 * DAY;
+   }
+
+
+
+   private final String            sqlDateFormat;
+   private final long              millisThreshold;
+   private final int               noOfChronoUnitsToAdd;
+   private final ChronoUnit        chronoUnitToAdd;
+   private final DateTimeFormatter selectedStringFormatter;
+   private final DateTimeFormatter humanStringFormatter;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   DateTimeGroupBy(String sqlDateFormat, long millisThreshold, int noOfChronoUnitsToAdd, ChronoUnit chronoUnitToAdd, DateTimeFormatter selectedStringFormatter, DateTimeFormatter humanStringFormatter)
+   {
+      this.sqlDateFormat = sqlDateFormat;
+      this.millisThreshold = millisThreshold;
+      this.noOfChronoUnitsToAdd = noOfChronoUnitsToAdd;
+      this.chronoUnitToAdd = chronoUnitToAdd;
+      this.selectedStringFormatter = selectedStringFormatter;
+      this.humanStringFormatter = humanStringFormatter;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String getSqlExpression()
+   {
+      ZoneId sessionOrInstanceZoneId = ValueUtils.getSessionOrInstanceZoneId();
+      return (getSqlExpression(sessionOrInstanceZoneId));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String getSqlExpression(ZoneId targetZoneId)
+   {
+      String targetTimezone = targetZoneId.toString();
+
+      if("Z".equals(targetTimezone) || !StringUtils.hasContent(targetTimezone))
+      {
+         targetTimezone = "UTC";
+      }
+
+      //////////////////////////////////////////////////////////////////////////////////////////////////////
+      // if we only had a timezone offset (not a zone name/id), then the zoneId's toString will look like //
+      // UTC-05:00.  MySQL doesn't want that, so, strip away the leading UTC, to just get -05:00          //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////
+      if((targetTimezone.startsWith("UTC-") || targetTimezone.startsWith("UTC+")) && targetTimezone.length() > 5)
+      {
+         targetTimezone = targetTimezone.substring(3);
+      }
+
+      return "DATE_FORMAT(CONVERT_TZ(%s, 'UTC', '" + targetTimezone + "'), '" + sqlDateFormat + "')";
+
+      /*
+      if(this == WEEK)
+      {
+         return "YEARWEEK(CONVERT_TZ(%s, 'UTC', '" + targetTimezone + "'), 6)";
+      }
+      else
+      {
+         return "DATE_FORMAT(CONVERT_TZ(%s, 'UTC', '" + targetTimezone + "'), '" + sqlDateFormat + "')";
+      }
+      */
+   }
+
+
+
+   /*******************************************************************************
+    ** get an instance of this enum, based on start & end instants - look at the #
+    ** of millis between them, and return the first enum value w/ a millisThreshold
+    ** under that difference.  Default to HOUR.
+    *******************************************************************************/
+   public static DateTimeGroupBy selectFromStartAndEndTimes(Instant start, Instant end)
+   {
+      long millisBetween = end.toEpochMilli() - start.toEpochMilli();
+      for(DateTimeGroupBy value : DateTimeGroupBy.values())
+      {
+         if(millisBetween > value.millisThreshold)
+         {
+            return (value);
+         }
+      }
+
+      return (HOUR);
+   }
+
+
+
+   /*******************************************************************************
+    ** Make an Instant into a string that will match what came out of the database's
+    ** DATE_FORMAT() function
+    *******************************************************************************/
+   public String makeSelectedString(Instant time)
+   {
+      return (makeSelectedString(time, ValueUtils.getSessionOrInstanceZoneId()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Make an Instant into a string that will match what came out of the database's
+    ** DATE_FORMAT() function
+    *******************************************************************************/
+   public String makeSelectedString(Instant time, ZoneId zoneId)
+   {
+      ZonedDateTime zoned = time.atZone(zoneId);
+
+      if(this == WEEK)
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////////
+         // so, it seems like database is returning, e.g., W00-W52, but java is doing W1-W53...            //
+         // which, apparently we can compensate for by adding a week?  not sure, but results seemed right. //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////
+         zoned = zoned.plusDays(7);
+         int weekYear = zoned.get(IsoFields.WEEK_BASED_YEAR);
+         int week     = zoned.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR);
+         return (String.format("%04dW%02d", weekYear, week));
+      }
+
+      return (selectedStringFormatter.format(zoned));
+   }
+
+
+
+   /*******************************************************************************
+    ** Make a string to show to a user
+    *******************************************************************************/
+   public String makeHumanString(Instant instant)
+   {
+      return (makeHumanString(instant, ValueUtils.getSessionOrInstanceZoneId()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Make a string to show to a user
+    *******************************************************************************/
+   public String makeHumanString(Instant instant, ZoneId zoneId)
+   {
+      ZonedDateTime zoned = instant.atZone(zoneId);
+      if(this.equals(WEEK))
+      {
+         DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern("M'/'d");
+
+         while(zoned.get(ChronoField.DAY_OF_WEEK) != DayOfWeek.SUNDAY.getValue())
+         {
+            ////////////////////////////////////////
+            // go backwards until sunday is found //
+            ////////////////////////////////////////
+            zoned = zoned.minus(1, ChronoUnit.DAYS);
+         }
+
+         return (dateTimeFormatter.format(zoned) + "-" + dateTimeFormatter.format(zoned.plusDays(6)));
+
+         /*
+         int               weekOfYear        = zoned.get(ChronoField.ALIGNED_WEEK_OF_YEAR);
+         ZonedDateTime     sunday            = zoned.with(IsoFields.WEEK_OF_WEEK_BASED_YEAR, weekOfYear).with(TemporalAdjusters.previousOrSame(DayOfWeek.SUNDAY));
+         ZonedDateTime     saturday          = sunday.with(TemporalAdjusters.next(DayOfWeek.SATURDAY));
+         DateTimeFormatter dateTimeFormatter = DateTimeFormatter.ofPattern("M'/'d");
+
+         return (dateTimeFormatter.format(sunday) + "-" + dateTimeFormatter.format(saturday));
+         */
+      }
+
+      return (humanStringFormatter.format(zoned));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Instant roundDown(Instant instant)
+   {
+      return roundDown(instant, ValueUtils.getSessionOrInstanceZoneId());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("checkstyle:indentation")
+   public Instant roundDown(Instant instant, ZoneId zoneId)
+   {
+      ZonedDateTime zoned = instant.atZone(zoneId);
+      return switch(this)
+      {
+         case YEAR -> zoned.with(TemporalAdjusters.firstDayOfYear()).truncatedTo(ChronoUnit.DAYS).toInstant();
+         case MONTH -> zoned.with(TemporalAdjusters.firstDayOfMonth()).truncatedTo(ChronoUnit.DAYS).toInstant();
+         case WEEK ->
+         {
+            while(zoned.get(ChronoField.DAY_OF_WEEK) != DayOfWeek.SUNDAY.getValue())
+            {
+               zoned = zoned.minusDays(1);
+            }
+            yield (zoned.truncatedTo(ChronoUnit.DAYS).toInstant());
+         }
+         case DAY -> zoned.truncatedTo(ChronoUnit.DAYS).toInstant();
+         case HOUR -> zoned.truncatedTo(ChronoUnit.HOURS).toInstant();
+      };
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Instant increment(Instant instant)
+   {
+      return (increment(instant, ValueUtils.getSessionOrInstanceZoneId()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Instant increment(Instant instant, ZoneId zoneId)
+   {
+      ZonedDateTime zoned = instant.atZone(zoneId);
+      return (zoned.plus(noOfChronoUnitsToAdd, chronoUnitToAdd).toInstant());
+   }
+}

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

@@ -0,0 +1,92 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+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.QWidgetData;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class DefaultWidgetRenderer extends AbstractWidgetRenderer
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      return new RenderWidgetOutput(new DefaultWidgetData(input));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static class DefaultWidgetData extends QWidgetData
+   {
+      private final String              type;
+      private final Map<String, String> queryParams;
+
+
+
+      /*******************************************************************************
+       ** Constructor
+       **
+       *******************************************************************************/
+      public DefaultWidgetData(RenderWidgetInput renderWidgetInput)
+      {
+         this.type = renderWidgetInput.getWidgetMetaData().getType();
+         this.queryParams = renderWidgetInput.getQueryParams();
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public String getType()
+      {
+         return (type);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for queryParams
+       **
+       *******************************************************************************/
+      public Map<String, String> getQueryParams()
+      {
+         return queryParams;
+      }
+   }
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import com.kingsrook.qqq.backend.core.actions.ActionHelper;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+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.DividerWidgetData;
+
+
+/*******************************************************************************
+ ** Generic widget for showing a divider
+ *******************************************************************************/
+public class DividerWidgetRenderer extends AbstractWidgetRenderer
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      ActionHelper.validateSession(input);
+      return (new RenderWidgetOutput(new DividerWidgetData()));
+   }
+}

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

@@ -0,0 +1,153 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import java.io.Serializable;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+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.RawHTML;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.AbstractWidgetOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.AbstractWidgetValueSource;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.QNoCodeWidgetMetaData;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.utils.BackendQueryFilterUtils;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class NoCodeWidgetRenderer extends AbstractWidgetRenderer
+{
+   private static final QLogger LOG = QLogger.getLogger(NoCodeWidgetRenderer.class);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      QNoCodeWidgetMetaData widgetMetaData = (QNoCodeWidgetMetaData) input.getWidgetMetaData();
+
+      Map<String, Object> context = initContext(input);
+      context.putAll(input.getQueryParams());
+
+      ///////////////////////////////////////////////
+      // populate context by evaluating all values //
+      ///////////////////////////////////////////////
+      for(AbstractWidgetValueSource valueSource : widgetMetaData.getValues())
+      {
+         try
+         {
+            LOG.trace("Computing: " + valueSource.getType() + " named " + valueSource.getName() + "...");
+            Object value = valueSource.evaluate(context, input);
+            LOG.trace("Computed: " + valueSource.getName() + " = " + value);
+            context.put(valueSource.getName(), value);
+            context.put(valueSource.getName() + ".source", valueSource);
+         }
+         catch(Exception e)
+         {
+            LOG.warn("Error evaluating widget value source", e, logPair("widgetName", input.getWidgetMetaData().getName()), logPair("valueSourceName", valueSource.getName()));
+         }
+      }
+
+      /////////////////////////////////////////////
+      // build content by evaluating all outputs //
+      /////////////////////////////////////////////
+      List<AbstractWidgetOutput> outputs = widgetMetaData.getOutputs();
+      String                     content = renderOutputs(context, outputs);
+
+      return (new RenderWidgetOutput(new RawHTML(widgetMetaData.getLabel(), content)));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Map<String, Object> initContext(RenderWidgetInput input)
+   {
+      Map<String, Object> context = new HashMap<>();
+      context.put("utils", new NoCodeWidgetVelocityUtils(context, input));
+      context.put("input", input);
+      return context;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String renderOutputs(Map<String, Object> context, List<AbstractWidgetOutput> outputs) throws QException
+   {
+      StringBuilder content = new StringBuilder();
+      for(AbstractWidgetOutput output : CollectionUtils.nonNullList(outputs))
+      {
+         boolean conditionPassed = true;
+         if(output.getCondition() != null)
+         {
+            conditionPassed = evaluateCondition(output.getCondition(), context);
+         }
+
+         if(conditionPassed)
+         {
+            String render = output.render(context);
+            content.append(render);
+            LOG.trace("Condition passed, rendered: " + render);
+         }
+         else
+         {
+            LOG.trace("Condition failed - not rendering this output.");
+         }
+      }
+      return (content.toString());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private boolean evaluateCondition(QFilterCriteria condition, Map<String, Object> context)
+   {
+      try
+      {
+         Object value = context.get(condition.getFieldName());
+         return (BackendQueryFilterUtils.doesCriteriaMatch(condition, condition.getFieldName(), (Serializable) value));
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error evaluating condition: " + condition, e);
+         return (false);
+      }
+   }
+
+}

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

@@ -0,0 +1,341 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.dashboard.AbstractHTMLWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.nocode.WidgetCount;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class NoCodeWidgetVelocityUtils
+{
+   private static final QLogger LOG = QLogger.getLogger(NoCodeWidgetVelocityUtils.class);
+
+   private Map<String, Object> context;
+   private RenderWidgetInput   input;
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public NoCodeWidgetVelocityUtils(Map<String, Object> context, RenderWidgetInput input)
+   {
+      this.context = context;
+      this.input = input;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String icon(String iconName, String color)
+   {
+      return String.format("""
+         <span class="material-icons-round notranslate MuiIcon-root MuiIcon-fontSizeInherit" style="color: %s; position: relative; top: 6px;" aria-hidden="true">%s</span>
+         """, color, iconName);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String helpIcon()
+   {
+      return (icon("help_outline", "blue"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String errorIcon()
+   {
+      return (icon("error_outline", "red"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String warningIcon()
+   {
+      return (icon("warning", "orange"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String checkIcon()
+   {
+      return (icon("check", "green"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String pendingIcon()
+   {
+      return (icon("pending", "#0062ff"));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String spanColorGreen()
+   {
+      return ("""
+         <span style="color: green;">
+         """);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String spanColorOrange()
+   {
+      return ("""
+         <span style="color: orange;">
+         """);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String spanColorRed()
+   {
+      return ("""
+         <span style="color: red;">
+         """);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String plural(Integer size, String ifOne, String ifNotOne)
+   {
+      return StringUtils.plural(size, ifOne, ifNotOne);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String formatDateTime(Instant i)
+   {
+      if(i == null)
+      {
+         return ("");
+      }
+      return QValueFormatter.formatDateTimeWithZone(i.atZone(ZoneId.of(QContext.getQInstance().getDefaultTimeZoneId())));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String formatSecondsAsDuration(Integer seconds)
+   {
+      StringBuilder rs = new StringBuilder();
+
+      if(seconds == null)
+      {
+         return ("");
+      }
+
+      int secondsPerDay = 24 * 60 * 60;
+      if(seconds >= secondsPerDay)
+      {
+         int days = seconds / (secondsPerDay);
+         seconds = seconds % secondsPerDay;
+         rs.append(days).append(StringUtils.plural(days, " day", " days")).append(" ");
+      }
+
+      int secondsPerHour = 60 * 60;
+      if(seconds >= secondsPerHour)
+      {
+         int hours = seconds / (secondsPerHour);
+         seconds = seconds % secondsPerHour;
+         rs.append(hours).append(StringUtils.plural(hours, " hour", " hours")).append(" ");
+      }
+
+      int secondsPerMinute = 60;
+      if(seconds >= secondsPerMinute)
+      {
+         int minutes = seconds / (secondsPerMinute);
+         seconds = seconds % secondsPerMinute;
+         rs.append(minutes).append(StringUtils.plural(minutes, " minute", " minutes")).append(" ");
+      }
+
+      if(seconds > 0 || rs.length() == 0)
+      {
+         rs.append(seconds).append(StringUtils.plural(seconds, " second", " seconds")).append(" ");
+      }
+
+      if(rs.length() > 0)
+      {
+         rs.deleteCharAt(rs.length() - 1);
+      }
+
+      return (rs.toString());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String formatSecondsAsRoundedDuration(Integer seconds)
+   {
+      StringBuilder rs = new StringBuilder();
+
+      if(seconds == null)
+      {
+         return ("");
+      }
+
+      int secondsPerDay = 24 * 60 * 60;
+      if(seconds >= secondsPerDay)
+      {
+         int days = seconds / (secondsPerDay);
+         return (days + StringUtils.plural(days, " day", " days"));
+      }
+
+      int secondsPerHour = 60 * 60;
+      if(seconds >= secondsPerHour)
+      {
+         int hours = seconds / (secondsPerHour);
+         return (hours + StringUtils.plural(hours, " hour", " hours"));
+      }
+
+      int secondsPerMinute = 60;
+      if(seconds >= secondsPerMinute)
+      {
+         int minutes = seconds / (secondsPerMinute);
+         return (minutes + StringUtils.plural(minutes, " minute", " minutes"));
+      }
+
+      if(seconds > 0 || rs.length() == 0)
+      {
+         return (seconds + StringUtils.plural(seconds, " second", " seconds"));
+      }
+
+      return ("");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String tableCountFilterLink(String countVariableName, String singular, String plural) throws QException
+   {
+      try
+      {
+         WidgetCount  widgetCount = (WidgetCount) context.get(countVariableName + ".source");
+         Integer      count       = ValueUtils.getValueAsInteger(context.get(countVariableName));
+         QQueryFilter filter      = widgetCount.getEffectiveFilter(input);
+         return (AbstractHTMLWidgetRenderer.aHrefTableFilterNoOfRecords(widgetCount.getTableName(), filter, count, singular, plural));
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error rendering widget link", e);
+         return ("");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String format(String displayFormat, Serializable value)
+   {
+      return (QValueFormatter.formatValue(displayFormat, value));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public String round(BigDecimal input, int digits)
+   {
+      return String.valueOf(input.setScale(digits, RoundingMode.HALF_UP));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Object ifElse(Object ifObject, Object elseObject)
+   {
+      if(StringUtils.hasContent(ValueUtils.getValueAsString(ifObject)))
+      {
+         return (ifObject);
+      }
+      else if(StringUtils.hasContent(ValueUtils.getValueAsString(elseObject)))
+      {
+         return (elseObject);
+      }
+
+      return ("");
+   }
+
+}

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

@@ -22,24 +22,12 @@
 package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 
-import java.util.ArrayList;
-import java.util.Comparator;
-import java.util.HashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
-import com.kingsrook.qqq.backend.core.actions.values.SearchPossibleValueSourceAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceInput;
-import com.kingsrook.qqq.backend.core.model.actions.values.SearchPossibleValueSourceOutput;
 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.ParentWidgetData;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.ParentWidgetMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
-import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
-import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
 
 /*******************************************************************************
@@ -65,42 +53,14 @@ public class ParentWidgetRenderer extends AbstractWidgetRenderer
          /////////////////////////////////////////////////////////////
          // handle any PVSs creating dropdown data for the frontend //
          /////////////////////////////////////////////////////////////
-         List<List<Map<String, String>>> pvsData   = new ArrayList<>();
-         List<String>                    pvsLabels = new ArrayList<>();
-         List<String>                    pvsNames  = new ArrayList<>();
-         for(String possibleValueSourceName : CollectionUtils.nonNullList(metaData.getPossibleValueNameList()))
+         boolean dropdownsValid = setupDropdowns(input, metaData, widgetData);
+
+         if(dropdownsValid)
          {
-            QPossibleValueSource possibleValueSource = input.getInstance().getPossibleValueSource(possibleValueSourceName);
-            pvsLabels.add(possibleValueSource.getLabel() != null ? possibleValueSource.getLabel() : possibleValueSourceName);
-            pvsNames.add(possibleValueSourceName);
-
-            SearchPossibleValueSourceInput pvsInput = new SearchPossibleValueSourceInput(input.getInstance());
-            pvsInput.setSession(input.getSession());
-            pvsInput.setPossibleValueSourceName(possibleValueSourceName);
-            SearchPossibleValueSourceOutput output = new SearchPossibleValueSourceAction().execute(pvsInput);
-
-            List<Map<String, String>> dropdownOptionList = new ArrayList<>();
-            pvsData.add(dropdownOptionList);
-
-            //////////////////////////////////////////
-            // sort results, dedupe, and add to map //
-            //////////////////////////////////////////
-            Set<String> exists = new HashSet<>();
-            output.getResults().removeIf(pvs -> !exists.add(pvs.getLabel()));
-            output.getResults().sort(Comparator.comparing(QPossibleValue::getLabel));
-            for(QPossibleValue<?> possibleValue : output.getResults())
-            {
-               dropdownOptionList.add(Map.of(
-                  "id", String.valueOf(possibleValue.getId()),
-                  "label", possibleValue.getLabel()
-               ));
-            }
+            widgetData.setChildWidgetNameList(metaData.getChildWidgetNameList());
          }
 
-         widgetData.setDropdownNameList(pvsNames);
-         widgetData.setDropdownLabelList(pvsLabels);
-         widgetData.setDropdownDataList(pvsData);
-         widgetData.setChildWidgetNameList(metaData.getChildWidgetNameList());
+         widgetData.setLayoutType(metaData.getLayoutType());
 
          return (new RenderWidgetOutput(widgetData));
       }

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

@@ -22,6 +22,7 @@
 package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
 
 
+import java.util.HashMap;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
@@ -53,9 +54,13 @@ public class ProcessWidgetRenderer extends AbstractWidgetRenderer
          ProcessWidgetData data = new ProcessWidgetData();
          if(input.getWidgetMetaData() instanceof QWidgetMetaData widgetMetaData)
          {
+            setupDropdowns(input, widgetMetaData, data);
+
             String           processName     = (String) widgetMetaData.getDefaultValues().get(WIDGET_PROCESS_NAME);
             QProcessMetaData processMetaData = input.getInstance().getProcess(processName);
             data.setProcessMetaData(processMetaData);
+
+            data.setDefaultValues(new HashMap<>(input.getQueryParams()));
          }
          return (new RenderWidgetOutput(data));
       }

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

@@ -26,7 +26,7 @@ import com.kingsrook.qqq.backend.core.actions.ActionHelper;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 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.QWidget;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.QWidgetData;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.QuickSightChart;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QuickSightChartMetaData;
 import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
@@ -74,8 +74,8 @@ public class QuickSightChartRenderer extends AbstractWidgetRenderer
 
          final GenerateEmbedUrlForRegisteredUserResponse generateEmbedUrlForRegisteredUserResponse = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);
 
-         String  embedUrl = generateEmbedUrlForRegisteredUserResponse.embedUrl();
-         QWidget widget   = new QuickSightChart(input.getWidgetMetaData().getName(), quickSightMetaData.getLabel(), embedUrl);
+         String      embedUrl = generateEmbedUrlForRegisteredUserResponse.embedUrl();
+         QWidgetData widget   = new QuickSightChart(input.getWidgetMetaData().getName(), quickSightMetaData.getLabel(), embedUrl);
          return (new RenderWidgetOutput(widget));
       }
       catch(Exception e)

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

@@ -0,0 +1,62 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.dashboard.widgets;
+
+
+import java.math.BigDecimal;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+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.USMapWidgetData;
+
+
+/*******************************************************************************
+ ** Generic widget for display a map of the us
+ *******************************************************************************/
+public class USMapWidgetRenderer extends AbstractWidgetRenderer
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+   {
+      return (new RenderWidgetOutput(
+         new USMapWidgetData()
+            .withHeight("250px")
+            .withMapMarkerList(generateMapMarkerList())
+      ));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   protected List<USMapWidgetData.MapMarker> generateMapMarkerList() throws QException
+   {
+      return (List.of(new USMapWidgetData.MapMarker("maryville", new BigDecimal("38.725278"), new BigDecimal("-89.957778"))));
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/AggregateInterface.java

@@ -31,7 +31,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateOu
  ** Interface for the Aggregate action.
  **
  *******************************************************************************/
-public interface AggregateInterface
+public interface AggregateInterface extends BaseQueryInterface
 {
    /*******************************************************************************
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/BaseQueryInterface.java

@@ -0,0 +1,81 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.interfaces;
+
+
+import java.time.Instant;
+import com.kingsrook.qqq.backend.core.model.querystats.QueryStat;
+
+
+/*******************************************************************************
+ ** Base class for "query" (e.g., read-operations) action interfaces (query, count, aggregate).
+ ** Initially just here for the QueryStat methods - if we expand those to apply
+ ** to insert/update/delete, well, then rename this maybe to BaseActionInterface?
+ *******************************************************************************/
+public interface BaseQueryInterface
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void setQueryStat(QueryStat queryStat)
+   {
+      //////////
+      // noop //
+      //////////
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default QueryStat getQueryStat()
+   {
+      return (null);
+   }
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void setQueryStatFirstResultTime()
+   {
+      QueryStat queryStat = getQueryStat();
+      if(queryStat != null)
+      {
+         if(queryStat.getFirstResultTimestamp() == null)
+         {
+            queryStat.setFirstResultTimestamp(Instant.now());
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void cancelAction()
+   {
+      //////////////////////////////////////////////
+      // initially at least, a noop in base class //
+      //////////////////////////////////////////////
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/CountInterface.java

@@ -31,7 +31,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountOutput;
  ** Interface for the Count action.
  **
  *******************************************************************************/
-public interface CountInterface
+public interface CountInterface extends BaseQueryInterface
 {
    /*******************************************************************************
     **

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/DeleteInterface.java

@@ -50,4 +50,13 @@ public interface DeleteInterface
       return (false);
    }
 
+   /*******************************************************************************
+    ** Specify whether this particular module's delete action can & should fetch
+    ** records before deleting them, e.g., for audits or "not-found-checks"
+    *******************************************************************************/
+   default boolean supportsPreFetchQuery()
+   {
+      return (true);
+   }
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/GetInterface.java

@@ -22,9 +22,13 @@
 package com.kingsrook.qqq.backend.core.actions.interfaces;
 
 
+import java.util.HashSet;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 
 
 /*******************************************************************************
@@ -37,4 +41,34 @@ public interface GetInterface
     **
     *******************************************************************************/
    GetOutput execute(GetInput getInput) throws QException;
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   default void validateInput(GetInput getInput) throws QException
+   {
+      if(getInput.getPrimaryKey() != null & getInput.getUniqueKey() != null)
+      {
+         throw new QException("A GetInput may not contain both a primary key [" + getInput.getPrimaryKey() + "] and unique key [" + getInput.getUniqueKey() + "]");
+      }
+
+      if(getInput.getUniqueKey() != null)
+      {
+         QTableMetaData table      = getInput.getTable();
+         boolean        foundMatch = false;
+         for(UniqueKey uniqueKey : CollectionUtils.nonNullList(table.getUniqueKeys()))
+         {
+            if(new HashSet<>(uniqueKey.getFieldNames()).equals(getInput.getUniqueKey().keySet()))
+            {
+               foundMatch = true;
+               break;
+            }
+         }
+
+         if(!foundMatch)
+         {
+            throw new QException("Table [" + table.getName() + "] does not have a unique key defined on fields: " + getInput.getUniqueKey().keySet().stream().sorted().toList());
+         }
+      }
+   }
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/QueryInterface.java

@@ -31,10 +31,11 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
  ** Interface for the Query action.
  **
  *******************************************************************************/
-public interface QueryInterface
+public interface QueryInterface extends BaseQueryInterface
 {
    /*******************************************************************************
     **
     *******************************************************************************/
    QueryOutput execute(QueryInput queryInput) throws QException;
+
 }

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/interfaces/UpdateInterface.java

@@ -37,4 +37,14 @@ public interface UpdateInterface
     **
     *******************************************************************************/
    UpdateOutput execute(UpdateInput updateInput) throws QException;
+
+   /*******************************************************************************
+    ** Specify whether this particular module's update action can & should fetch
+    ** records before updating them, e.g., for audits or "not-found-checks"
+    *******************************************************************************/
+   default boolean supportsPreFetchQuery()
+   {
+      return (true);
+   }
+
 }

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

@@ -0,0 +1,336 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.metadata;
+
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.TreeSet;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** Object to represent the graph of joins in a QQQ Instance.  e.g., all of the
+ ** connections among tables through joins.
+ *******************************************************************************/
+public class JoinGraph
+{
+
+   private Set<Edge> edges = new HashSet<>();
+
+
+
+   /*******************************************************************************
+    ** Graph edge (no graph nodes needed in here)
+    *******************************************************************************/
+   private record Edge(String joinName, String leftTable, String rightTable)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** In this class, we are treating joins as non-directional graph edges - so -
+    ** use this class to "normalize" what may otherwise be duplicated joins in the
+    ** qInstance (e.g., A -> B and B -> A -- in the instance, those are valid, but
+    ** in our graph here, we want to consider those the same).
+    *******************************************************************************/
+   private static class NormalizedJoin
+   {
+      private String tableA;
+      private String tableB;
+      private String joinFieldA;
+      private String joinFieldB;
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public NormalizedJoin(QJoinMetaData joinMetaData)
+      {
+         boolean needFlip     = false;
+         int     tableCompare = joinMetaData.getLeftTable().compareTo(joinMetaData.getRightTable());
+         if(tableCompare < 0)
+         {
+            needFlip = true;
+         }
+         else if(tableCompare == 0)
+         {
+            int fieldCompare = joinMetaData.getJoinOns().get(0).getLeftField().compareTo(joinMetaData.getJoinOns().get(0).getRightField());
+            if(fieldCompare < 0)
+            {
+               needFlip = true;
+            }
+         }
+
+         if(needFlip)
+         {
+            joinMetaData = joinMetaData.flip();
+         }
+
+         tableA = joinMetaData.getLeftTable();
+         tableB = joinMetaData.getRightTable();
+         joinFieldA = joinMetaData.getJoinOns().get(0).getLeftField();
+         joinFieldB = joinMetaData.getJoinOns().get(0).getRightField();
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public boolean equals(Object o)
+      {
+         if(this == o)
+         {
+            return true;
+         }
+         if(o == null || getClass() != o.getClass())
+         {
+            return false;
+         }
+         NormalizedJoin that = (NormalizedJoin) o;
+         return Objects.equals(tableA, that.tableA) && Objects.equals(tableB, that.tableB) && Objects.equals(joinFieldA, that.joinFieldA) && Objects.equals(joinFieldB, that.joinFieldB);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public int hashCode()
+      {
+         return Objects.hash(tableA, tableB, joinFieldA, joinFieldB);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor
+    **
+    *******************************************************************************/
+   public JoinGraph(QInstance qInstance)
+   {
+      Set<NormalizedJoin> usedJoins = new HashSet<>();
+      for(QJoinMetaData join : CollectionUtils.nonNullMap(qInstance.getJoins()).values())
+      {
+         NormalizedJoin normalizedJoin = new NormalizedJoin(join);
+         if(usedJoins.contains(normalizedJoin))
+         {
+            continue;
+         }
+
+         usedJoins.add(normalizedJoin);
+         edges.add(new Edge(join.getName(), join.getLeftTable(), join.getRightTable()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public record JoinConnection(String joinTable, String viaJoinName) implements Comparable<JoinConnection>
+   {
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public int compareTo(JoinConnection that)
+      {
+         Comparator<JoinConnection> comparator = Comparator.comparing((JoinConnection jc) -> jc.joinTable())
+            .thenComparing((JoinConnection jc) -> jc.viaJoinName());
+         return (comparator.compare(this, that));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public record JoinConnectionList(List<JoinConnection> list) implements Comparable<JoinConnectionList>
+   {
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public JoinConnectionList copy()
+      {
+         return new JoinConnectionList(new ArrayList<>(list));
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public int compareTo(JoinConnectionList that)
+      {
+         if(this.equals(that))
+         {
+            return (0);
+         }
+
+         for(int i = 0; i < Math.min(this.list.size(), that.list.size()); i++)
+         {
+            int comp = this.list.get(i).compareTo(that.list.get(i));
+            if(comp != 0)
+            {
+               return (comp);
+            }
+         }
+
+         return (this.list.size() - that.list.size());
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public boolean matchesJoinPath(List<String> joinPath)
+      {
+         if(list.size() != joinPath.size())
+         {
+            return (false);
+         }
+
+         for(int i = 0; i < list.size(); i++)
+         {
+            if(!list.get(i).viaJoinName().equals(joinPath.get(i)))
+            {
+               return (false);
+            }
+         }
+
+         return (true);
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public String getJoinNamesAsString()
+      {
+         return (StringUtils.join(", ", list().stream().map(jc -> jc.viaJoinName()).toList()));
+      }
+
+
+
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      public List<String> getJoinNamesAsList()
+      {
+         return (list().stream().map(jc -> jc.viaJoinName()).toList());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Set<JoinConnectionList> getJoinConnections(String tableName)
+   {
+      Set<JoinConnectionList> rs = new TreeSet<>();
+      doGetJoinConnections(rs, tableName, new ArrayList<>(), new JoinConnectionList(new ArrayList<>()));
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void doGetJoinConnections(Set<JoinConnectionList> joinConnections, String tableName, List<String> path, JoinConnectionList connectionList)
+   {
+      for(Edge edge : edges)
+      {
+         if(edge.leftTable.equals(tableName) || edge.rightTable.equals(tableName))
+         {
+            if(path.contains(edge.joinName))
+            {
+               continue;
+            }
+
+            List<String> newPath = new ArrayList<>(path);
+            newPath.add(edge.joinName);
+            if(!joinConnectionsContain(joinConnections, newPath))
+            {
+               String otherTableName = null;
+               if(!edge.leftTable.equals(tableName))
+               {
+                  otherTableName = edge.leftTable;
+               }
+               else if(!edge.rightTable.equals(tableName))
+               {
+                  otherTableName = edge.rightTable;
+               }
+
+               if(otherTableName != null)
+               {
+
+                  JoinConnectionList newConnectionList = connectionList.copy();
+                  JoinConnection     joinConnection    = new JoinConnection(otherTableName, edge.joinName);
+                  newConnectionList.list.add(joinConnection);
+                  joinConnections.add(newConnectionList);
+                  doGetJoinConnections(joinConnections, otherTableName, new ArrayList<>(newPath), newConnectionList);
+               }
+            }
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private boolean joinConnectionsContain(Set<JoinConnectionList> joinPaths, List<String> newPath)
+   {
+      for(JoinConnectionList joinConnections : joinPaths)
+      {
+         List<String> joinConnectionJoins = joinConnections.list.stream().map(jc -> jc.viaJoinName).toList();
+         if(joinConnectionJoins.equals(newPath))
+         {
+            return (true);
+         }
+      }
+      return (false);
+   }
+
+}

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

@@ -27,6 +27,8 @@ 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.permissions.PermissionCheckResult;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataInput;
 import com.kingsrook.qqq.backend.core.model.actions.metadata.MetaDataOutput;
@@ -40,6 +42,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendTableMeta
 import com.kingsrook.qqq.backend.core.model.metadata.frontend.QFrontendWidgetMetaData;
 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.permissions.MetaDataWithPermissionRules;
 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;
@@ -70,21 +73,41 @@ public class MetaDataAction
       Map<String, QFrontendTableMetaData> tables = new LinkedHashMap<>();
       for(Map.Entry<String, QTableMetaData> entry : metaDataInput.getInstance().getTables().entrySet())
       {
-         String           tableName       = entry.getKey();
+         String         tableName = entry.getKey();
+         QTableMetaData table     = entry.getValue();
+
+         PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, table);
+         if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
+         {
+            continue;
+         }
+
          QBackendMetaData backendForTable = metaDataInput.getInstance().getBackendForTable(tableName);
-         tables.put(tableName, new QFrontendTableMetaData(backendForTable, entry.getValue(), false));
-         treeNodes.put(tableName, new AppTreeNode(entry.getValue()));
+         tables.put(tableName, new QFrontendTableMetaData(metaDataInput, backendForTable, table, false, false));
+         treeNodes.put(tableName, new AppTreeNode(table));
       }
       metaDataOutput.setTables(tables);
 
+      // addJoinsToTables(tables);
+      // addJoinedTablesToTables(tables);
+
       ////////////////////////////////////////
       // map processes to frontend metadata //
       ////////////////////////////////////////
       Map<String, QFrontendProcessMetaData> processes = new LinkedHashMap<>();
       for(Map.Entry<String, QProcessMetaData> entry : metaDataInput.getInstance().getProcesses().entrySet())
       {
-         processes.put(entry.getKey(), new QFrontendProcessMetaData(entry.getValue(), false));
-         treeNodes.put(entry.getKey(), new AppTreeNode(entry.getValue()));
+         String           processName = entry.getKey();
+         QProcessMetaData process     = entry.getValue();
+
+         PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, process);
+         if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
+         {
+            continue;
+         }
+
+         processes.put(processName, new QFrontendProcessMetaData(metaDataInput, process, false));
+         treeNodes.put(processName, new AppTreeNode(process));
       }
       metaDataOutput.setProcesses(processes);
 
@@ -94,8 +117,17 @@ public class MetaDataAction
       Map<String, QFrontendReportMetaData> reports = new LinkedHashMap<>();
       for(Map.Entry<String, QReportMetaData> entry : metaDataInput.getInstance().getReports().entrySet())
       {
-         reports.put(entry.getKey(), new QFrontendReportMetaData(entry.getValue(), false));
-         treeNodes.put(entry.getKey(), new AppTreeNode(entry.getValue()));
+         String          reportName = entry.getKey();
+         QReportMetaData report     = entry.getValue();
+
+         PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, report);
+         if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
+         {
+            continue;
+         }
+
+         reports.put(reportName, new QFrontendReportMetaData(metaDataInput, report, false));
+         treeNodes.put(reportName, new AppTreeNode(report));
       }
       metaDataOutput.setReports(reports);
 
@@ -105,7 +137,16 @@ public class MetaDataAction
       Map<String, QFrontendWidgetMetaData> widgets = new LinkedHashMap<>();
       for(Map.Entry<String, QWidgetMetaDataInterface> entry : metaDataInput.getInstance().getWidgets().entrySet())
       {
-         widgets.put(entry.getKey(), new QFrontendWidgetMetaData(entry.getValue()));
+         String                   widgetName = entry.getKey();
+         QWidgetMetaDataInterface widget     = entry.getValue();
+
+         PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, widget);
+         if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
+         {
+            continue;
+         }
+
+         widgets.put(widgetName, new QFrontendWidgetMetaData(metaDataInput, widget));
       }
       metaDataOutput.setWidgets(widgets);
 
@@ -115,14 +156,32 @@ public class MetaDataAction
       Map<String, QFrontendAppMetaData> apps = new LinkedHashMap<>();
       for(Map.Entry<String, QAppMetaData> entry : metaDataInput.getInstance().getApps().entrySet())
       {
-         apps.put(entry.getKey(), new QFrontendAppMetaData(entry.getValue()));
-         treeNodes.put(entry.getKey(), new AppTreeNode(entry.getValue()));
+         String       appName = entry.getKey();
+         QAppMetaData app     = entry.getValue();
 
-         if(CollectionUtils.nullSafeHasContents(entry.getValue().getChildren()))
+         PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, app);
+         if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
          {
-            for(QAppChildMetaData child : entry.getValue().getChildren())
+            continue;
+         }
+
+         apps.put(appName, new QFrontendAppMetaData(app, metaDataOutput));
+         treeNodes.put(appName, new AppTreeNode(app));
+
+         if(CollectionUtils.nullSafeHasContents(app.getChildren()))
+         {
+            for(QAppChildMetaData child : app.getChildren())
             {
-               apps.get(entry.getKey()).addChild(new AppTreeNode(child));
+               if(child instanceof MetaDataWithPermissionRules metaDataWithPermissionRules)
+               {
+                  PermissionCheckResult childPermissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, metaDataWithPermissionRules);
+                  if(childPermissionResult.equals(PermissionCheckResult.DENY_HIDE))
+                  {
+                     continue;
+                  }
+               }
+
+               apps.get(appName).addChild(new AppTreeNode(child));
             }
          }
       }
@@ -136,7 +195,7 @@ public class MetaDataAction
       {
          if(appMetaData.getParentAppName() == null)
          {
-            buildAppTree(treeNodes, appTree, appMetaData);
+            buildAppTree(metaDataInput, treeNodes, appTree, appMetaData);
          }
       }
       metaDataOutput.setAppTree(appTree);
@@ -149,6 +208,8 @@ public class MetaDataAction
          metaDataOutput.setBranding(metaDataInput.getInstance().getBranding());
       }
 
+      metaDataOutput.setEnvironmentValues(metaDataInput.getInstance().getEnvironmentValues());
+
       // todo post-customization - can do whatever w/ the result if you want?
 
       return metaDataOutput;
@@ -159,7 +220,7 @@ public class MetaDataAction
    /*******************************************************************************
     **
     *******************************************************************************/
-   private void buildAppTree(Map<String, AppTreeNode> treeNodes, List<AppTreeNode> nodeList, QAppChildMetaData childMetaData)
+   private void buildAppTree(MetaDataInput metaDataInput, Map<String, AppTreeNode> treeNodes, List<AppTreeNode> nodeList, QAppChildMetaData childMetaData)
    {
       AppTreeNode treeNode = treeNodes.get(childMetaData.getName());
       if(treeNode == null)
@@ -174,7 +235,16 @@ public class MetaDataAction
          {
             for(QAppChildMetaData child : app.getChildren())
             {
-               buildAppTree(treeNodes, treeNode.getChildren(), child);
+               if(child instanceof MetaDataWithPermissionRules metaDataWithPermissionRules)
+               {
+                  PermissionCheckResult permissionResult = PermissionsHelper.getPermissionCheckResult(metaDataInput, metaDataWithPermissionRules);
+                  if(permissionResult.equals(PermissionCheckResult.DENY_HIDE))
+                  {
+                     continue;
+                  }
+               }
+
+               buildAppTree(metaDataInput, treeNodes, treeNode.getChildren(), child);
             }
          }
       }

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

@@ -52,7 +52,7 @@ public class ProcessMetaDataAction
       {
          throw (new QNotFoundException("Process [" + processMetaDataInput.getProcessName() + "] was not found."));
       }
-      processMetaDataOutput.setProcess(new QFrontendProcessMetaData(process, true));
+      processMetaDataOutput.setProcess(new QFrontendProcessMetaData(processMetaDataInput, process, true));
 
       // todo post-customization - can do whatever w/ the result if you want
 

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

@@ -54,7 +54,7 @@ public class TableMetaDataAction
          throw (new QNotFoundException("Table [" + tableMetaDataInput.getTableName() + "] was not found."));
       }
       QBackendMetaData backendForTable = tableMetaDataInput.getInstance().getBackendForTable(table.getName());
-      tableMetaDataOutput.setTable(new QFrontendTableMetaData(backendForTable, table, true));
+      tableMetaDataOutput.setTable(new QFrontendTableMetaData(tableMetaDataInput, backendForTable, table, true, true));
 
       // todo post-customization - can do whatever w/ the result if you want
 

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/AvailablePermission.java

@@ -0,0 +1,204 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+import java.util.Objects;
+import com.kingsrook.qqq.backend.core.model.data.QField;
+import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class AvailablePermission extends QRecordEntity
+{
+   public static final String TABLE_NAME = "availablePermission";
+
+   @QField(label = "Permission Name")
+   private String name;
+
+   @QField(label = "Object")
+   private String objectName;
+
+   @QField()
+   private String objectType;
+
+   @QField()
+   private String permissionType;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public boolean equals(Object o)
+   {
+      if(this == o)
+      {
+         return true;
+      }
+      if(o == null || getClass() != o.getClass())
+      {
+         return false;
+      }
+      AvailablePermission that = (AvailablePermission) o;
+      return Objects.equals(name, that.name) && Objects.equals(objectName, that.objectName) && Objects.equals(objectType, that.objectType) && Objects.equals(permissionType, that.permissionType);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public int hashCode()
+   {
+      return Objects.hash(name, objectName, objectType, permissionType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for name
+    *******************************************************************************/
+   public String getName()
+   {
+      return (this.name);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for name
+    *******************************************************************************/
+   public void setName(String name)
+   {
+      this.name = name;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for name
+    *******************************************************************************/
+   public AvailablePermission withName(String name)
+   {
+      this.name = name;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for objectType
+    *******************************************************************************/
+   public String getObjectType()
+   {
+      return (this.objectType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for objectType
+    *******************************************************************************/
+   public void setObjectType(String objectType)
+   {
+      this.objectType = objectType;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for objectType
+    *******************************************************************************/
+   public AvailablePermission withObjectType(String objectType)
+   {
+      this.objectType = objectType;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for permissionType
+    *******************************************************************************/
+   public String getPermissionType()
+   {
+      return (this.permissionType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for permissionType
+    *******************************************************************************/
+   public void setPermissionType(String permissionType)
+   {
+      this.permissionType = permissionType;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for permissionType
+    *******************************************************************************/
+   public AvailablePermission withPermissionType(String permissionType)
+   {
+      this.permissionType = permissionType;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for objectName
+    *******************************************************************************/
+   public String getObjectName()
+   {
+      return (this.objectName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for objectName
+    *******************************************************************************/
+   public void setObjectName(String objectName)
+   {
+      this.objectName = objectName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for objectName
+    *******************************************************************************/
+   public AvailablePermission withObjectName(String objectName)
+   {
+      this.objectName = objectName;
+      return (this);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/BulkTableActionProcessPermissionChecker.java

@@ -0,0 +1,67 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class BulkTableActionProcessPermissionChecker implements CustomPermissionChecker
+{
+   private static final QLogger LOG = QLogger.getLogger(BulkTableActionProcessPermissionChecker.class);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void checkPermissionsThrowing(AbstractActionInput actionInput, MetaDataWithPermissionRules metaDataWithPermissionRules) throws QPermissionDeniedException
+   {
+      String processName = metaDataWithPermissionRules.getName();
+      if(processName != null && processName.indexOf('.') > -1)
+      {
+         String[] parts          = processName.split("\\.", 2);
+         String   tableName      = parts[0];
+         String   bulkActionName = parts[1];
+
+         AbstractTableActionInput tableActionInput = new AbstractTableActionInput();
+         tableActionInput.setTableName(tableName);
+
+         switch(bulkActionName)
+         {
+            case "bulkInsert" -> PermissionsHelper.checkTablePermissionThrowing(tableActionInput, TablePermissionSubType.INSERT);
+            case "bulkEdit" -> PermissionsHelper.checkTablePermissionThrowing(tableActionInput, TablePermissionSubType.EDIT);
+            case "bulkDelete" -> PermissionsHelper.checkTablePermissionThrowing(tableActionInput, TablePermissionSubType.DELETE);
+            default -> LOG.warn("Unexpected bulk action name when checking permissions for process: " + processName);
+         }
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/CustomPermissionChecker.java

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

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/PermissionCheckResult.java

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

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/PermissionSubType.java

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

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/PermissionsHelper.java

@@ -0,0 +1,602 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.stream.Collectors;
+import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractTableActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+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.permissions.DenyBehavior;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithName;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
+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.model.session.QSession;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class PermissionsHelper
+{
+   private static final QLogger LOG = QLogger.getLogger(PermissionsHelper.class);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkTablePermissionThrowing(AbstractTableActionInput tableActionInput, TablePermissionSubType permissionSubType) throws QPermissionDeniedException
+   {
+      checkTablePermissionThrowing(tableActionInput, tableActionInput.getTableName(), permissionSubType);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void checkTablePermissionThrowing(AbstractActionInput actionInput, String tableName, TablePermissionSubType permissionSubType) throws QPermissionDeniedException
+   {
+      warnAboutPermissionSubTypeForTables(permissionSubType);
+      QTableMetaData table = QContext.getQInstance().getTable(tableName);
+
+      commonCheckPermissionThrowing(getEffectivePermissionRules(table, QContext.getQInstance()), permissionSubType, table.getName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static String getTablePermissionName(String tableName, TablePermissionSubType permissionSubType)
+   {
+      QInstance        qInstance          = QContext.getQInstance();
+      QPermissionRules rules              = getEffectivePermissionRules(qInstance.getTable(tableName), qInstance);
+      String           permissionBaseName = getEffectivePermissionBaseName(rules, tableName);
+      return (getPermissionName(permissionBaseName, permissionSubType));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static boolean hasTablePermission(AbstractActionInput actionInput, String tableName, TablePermissionSubType permissionSubType)
+   {
+      try
+      {
+         checkTablePermissionThrowing(actionInput, tableName, permissionSubType);
+         return (true);
+      }
+      catch(QPermissionDeniedException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static PermissionCheckResult getPermissionCheckResult(AbstractActionInput actionInput, MetaDataWithPermissionRules metaDataWithPermissionRules)
+   {
+      QPermissionRules rules              = getEffectivePermissionRules(metaDataWithPermissionRules, QContext.getQInstance());
+      String           permissionBaseName = getEffectivePermissionBaseName(rules, metaDataWithPermissionRules.getName());
+
+      switch(rules.getLevel())
+      {
+         case NOT_PROTECTED:
+         {
+            /////////////////////////////////////////////////
+            // if the entity isn't protected, always ALLOW //
+            /////////////////////////////////////////////////
+            return PermissionCheckResult.ALLOW;
+         }
+         case HAS_ACCESS_PERMISSION:
+         {
+            ////////////////////////////////////////////////////////////////////////
+            // if the entity just has a 'has access', then check for 'has access' //
+            ////////////////////////////////////////////////////////////////////////
+            return getPermissionCheckResult(actionInput, rules, permissionBaseName, metaDataWithPermissionRules, PrivatePermissionSubType.HAS_ACCESS);
+         }
+         case READ_WRITE_PERMISSIONS:
+         {
+            ////////////////////////////////////////////////////////////////
+            // if the table is configured w/ read/write, check for either //
+            ////////////////////////////////////////////////////////////////
+            if(metaDataWithPermissionRules instanceof QTableMetaData)
+            {
+               return getPermissionCheckResult(actionInput, rules, permissionBaseName, metaDataWithPermissionRules, PrivatePermissionSubType.READ, PrivatePermissionSubType.WRITE);
+            }
+            return getPermissionCheckResult(actionInput, rules, permissionBaseName, metaDataWithPermissionRules, PrivatePermissionSubType.HAS_ACCESS);
+         }
+         case READ_INSERT_EDIT_DELETE_PERMISSIONS:
+         {
+            //////////////////////////////////////////////////////////////////////////
+            // if the table is configured w/ read/insert/edit/delete, check for any //
+            //////////////////////////////////////////////////////////////////////////
+            if(metaDataWithPermissionRules instanceof QTableMetaData)
+            {
+               return getPermissionCheckResult(actionInput, rules, permissionBaseName, metaDataWithPermissionRules, TablePermissionSubType.READ, TablePermissionSubType.INSERT, TablePermissionSubType.EDIT, TablePermissionSubType.DELETE);
+            }
+            return getPermissionCheckResult(actionInput, rules, permissionBaseName, metaDataWithPermissionRules, PrivatePermissionSubType.HAS_ACCESS);
+         }
+         default:
+         {
+            return getPermissionDeniedCheckResult(rules);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkProcessPermissionThrowing(AbstractActionInput actionInput, String processName) throws QPermissionDeniedException
+   {
+      checkProcessPermissionThrowing(actionInput, processName, Collections.emptyMap());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkProcessPermissionThrowing(AbstractActionInput actionInput, String processName, Map<String, Serializable> processValues) throws QPermissionDeniedException
+   {
+      QProcessMetaData process                  = QContext.getQInstance().getProcess(processName);
+      QPermissionRules effectivePermissionRules = getEffectivePermissionRules(process, QContext.getQInstance());
+
+      if(effectivePermissionRules.getCustomPermissionChecker() != null)
+      {
+         /////////////////////////////////////
+         // todo - avoid stack overflows... //
+         /////////////////////////////////////
+         CustomPermissionChecker customPermissionChecker = QCodeLoader.getAdHoc(CustomPermissionChecker.class, effectivePermissionRules.getCustomPermissionChecker());
+         customPermissionChecker.checkPermissionsThrowing(actionInput, process);
+         return;
+      }
+
+      commonCheckPermissionThrowing(effectivePermissionRules, PrivatePermissionSubType.HAS_ACCESS, process.getName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static boolean hasProcessPermission(AbstractActionInput actionInput, String processName)
+   {
+      try
+      {
+         checkProcessPermissionThrowing(actionInput, processName);
+         return (true);
+      }
+      catch(QPermissionDeniedException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkAppPermissionThrowing(AbstractActionInput actionInput, String appName) throws QPermissionDeniedException
+   {
+      QAppMetaData app = QContext.getQInstance().getApp(appName);
+      commonCheckPermissionThrowing(getEffectivePermissionRules(app, QContext.getQInstance()), PrivatePermissionSubType.HAS_ACCESS, app.getName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static boolean hasAppPermission(AbstractActionInput actionInput, String appName)
+   {
+      try
+      {
+         checkAppPermissionThrowing(actionInput, appName);
+         return (true);
+      }
+      catch(QPermissionDeniedException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkReportPermissionThrowing(AbstractActionInput actionInput, String reportName) throws QPermissionDeniedException
+   {
+      QReportMetaData report = QContext.getQInstance().getReport(reportName);
+      commonCheckPermissionThrowing(getEffectivePermissionRules(report, QContext.getQInstance()), PrivatePermissionSubType.HAS_ACCESS, report.getName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static boolean hasReportPermission(AbstractActionInput actionInput, String reportName)
+   {
+      try
+      {
+         checkReportPermissionThrowing(actionInput, reportName);
+         return (true);
+      }
+      catch(QPermissionDeniedException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static void checkWidgetPermissionThrowing(AbstractActionInput actionInput, String widgetName) throws QPermissionDeniedException
+   {
+      QWidgetMetaDataInterface widget = QContext.getQInstance().getWidget(widgetName);
+      commonCheckPermissionThrowing(getEffectivePermissionRules(widget, QContext.getQInstance()), PrivatePermissionSubType.HAS_ACCESS, widget.getName());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static boolean hasWidgetPermission(AbstractActionInput actionInput, String widgetName)
+   {
+      try
+      {
+         checkWidgetPermissionThrowing(actionInput, widgetName);
+         return (true);
+      }
+      catch(QPermissionDeniedException e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static Collection<String> getAllAvailablePermissionNames(QInstance instance)
+   {
+      return (getAllAvailablePermissions(instance).stream()
+         .map(AvailablePermission::getName)
+         .collect(Collectors.toCollection(LinkedHashSet::new)));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static Collection<AvailablePermission> getAllAvailablePermissions(QInstance instance)
+   {
+      Collection<AvailablePermission> rs = new LinkedHashSet<>();
+
+      for(QTableMetaData tableMetaData : instance.getTables().values())
+      {
+         if(tableMetaData.getIsHidden())
+         {
+            continue;
+         }
+
+         QPermissionRules rules    = getEffectivePermissionRules(tableMetaData, instance);
+         String           baseName = getEffectivePermissionBaseName(rules, tableMetaData.getName());
+
+         for(TablePermissionSubType permissionSubType : TablePermissionSubType.values())
+         {
+            addEffectiveAvailablePermission(rules, permissionSubType, rs, baseName, tableMetaData, "Table");
+         }
+      }
+
+      for(QProcessMetaData processMetaData : instance.getProcesses().values())
+      {
+         if(processMetaData.getIsHidden())
+         {
+            continue;
+         }
+
+         QPermissionRules rules    = getEffectivePermissionRules(processMetaData, instance);
+         String           baseName = getEffectivePermissionBaseName(rules, processMetaData.getName());
+         addEffectiveAvailablePermission(rules, PrivatePermissionSubType.HAS_ACCESS, rs, baseName, processMetaData, "Process");
+      }
+
+      for(QAppMetaData appMetaData : instance.getApps().values())
+      {
+         QPermissionRules rules    = getEffectivePermissionRules(appMetaData, instance);
+         String           baseName = getEffectivePermissionBaseName(rules, appMetaData.getName());
+         addEffectiveAvailablePermission(rules, PrivatePermissionSubType.HAS_ACCESS, rs, baseName, appMetaData, "App");
+      }
+
+      for(QReportMetaData reportMetaData : instance.getReports().values())
+      {
+         QPermissionRules rules    = getEffectivePermissionRules(reportMetaData, instance);
+         String           baseName = getEffectivePermissionBaseName(rules, reportMetaData.getName());
+         addEffectiveAvailablePermission(rules, PrivatePermissionSubType.HAS_ACCESS, rs, baseName, reportMetaData, "Report");
+      }
+
+      for(QWidgetMetaDataInterface widgetMetaData : instance.getWidgets().values())
+      {
+         QPermissionRules rules    = getEffectivePermissionRules(widgetMetaData, instance);
+         String           baseName = getEffectivePermissionBaseName(rules, widgetMetaData.getName());
+         addEffectiveAvailablePermission(rules, PrivatePermissionSubType.HAS_ACCESS, rs, baseName, widgetMetaData, "Widget");
+      }
+
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void addEffectiveAvailablePermission(QPermissionRules rules, PermissionSubType permissionSubType, Collection<AvailablePermission> rs, String baseName, MetaDataWithName metaDataWithName, String objectType)
+   {
+      PermissionSubType effectivePermissionSubType = getEffectivePermissionSubType(rules, permissionSubType);
+      if(effectivePermissionSubType != null)
+      {
+         rs.add(new AvailablePermission()
+            .withName(getPermissionName(baseName, effectivePermissionSubType))
+            .withObjectName(metaDataWithName.getLabel())
+            .withPermissionType(effectivePermissionSubType.toString())
+            .withObjectType(objectType));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static QPermissionRules getEffectivePermissionRules(MetaDataWithPermissionRules metaDataWithPermissionRules, QInstance instance)
+   {
+      if(metaDataWithPermissionRules.getPermissionRules() == null)
+      {
+         LOG.warn("Null permission rules on meta data object [" + metaDataWithPermissionRules.getClass().getSimpleName() + "][" + metaDataWithPermissionRules.getName() + "] - does the instance need enriched?  Returning instance default rules.");
+         return (instance.getDefaultPermissionRules());
+      }
+      return (metaDataWithPermissionRules.getPermissionRules());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static boolean hasPermission(QSession session, String permissionBaseName, PermissionSubType permissionSubType)
+   {
+      if(permissionSubType == null)
+      {
+         return (true);
+      }
+
+      String permissionName = getPermissionName(permissionBaseName, permissionSubType);
+      return (session.hasPermission(permissionName));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static PermissionCheckResult getPermissionCheckResult(AbstractActionInput actionInput, QPermissionRules rules, String permissionBaseName, MetaDataWithPermissionRules metaDataWithPermissionRules, PermissionSubType... permissionSubTypes)
+   {
+      for(PermissionSubType permissionSubType : permissionSubTypes)
+      {
+         PermissionSubType effectivePermissionSubType = getEffectivePermissionSubType(rules, permissionSubType);
+
+         if(rules.getCustomPermissionChecker() != null)
+         {
+            try
+            {
+               CustomPermissionChecker customPermissionChecker = QCodeLoader.getAdHoc(CustomPermissionChecker.class, rules.getCustomPermissionChecker());
+               customPermissionChecker.checkPermissionsThrowing(actionInput, metaDataWithPermissionRules);
+               return (PermissionCheckResult.ALLOW);
+            }
+            catch(QPermissionDeniedException e)
+            {
+               return (getPermissionDeniedCheckResult(rules));
+            }
+         }
+
+         if(hasPermission(QContext.getQSession(), permissionBaseName, effectivePermissionSubType))
+         {
+            return (PermissionCheckResult.ALLOW);
+         }
+      }
+
+      return (getPermissionDeniedCheckResult(rules));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String getEffectivePermissionBaseName(QPermissionRules rules, String standardName)
+   {
+      if(rules != null && StringUtils.hasContent(rules.getPermissionBaseName()))
+      {
+         return (rules.getPermissionBaseName());
+      }
+
+      return (standardName);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("checkstyle:indentation")
+   static PermissionSubType getEffectivePermissionSubType(QPermissionRules rules, PermissionSubType originalPermissionSubType)
+   {
+      if(rules == null || rules.getLevel() == null)
+      {
+         return (originalPermissionSubType);
+      }
+
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // if the original permission sub-type is "hasAccess" - then this is a check for a process/report/widget. //
+      // in that case - never return the table-level read/write/insert/edit/delete options                      //
+      ////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      if(PrivatePermissionSubType.HAS_ACCESS.equals(originalPermissionSubType))
+      {
+         return switch(rules.getLevel())
+            {
+               case NOT_PROTECTED -> null;
+               default -> PrivatePermissionSubType.HAS_ACCESS;
+            };
+      }
+      else
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // else, this is a table check - so - based on the rules being used for this table, map the requested //
+         // permission sub-type to what we expect to be set for the table                                      //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////
+         return switch(rules.getLevel())
+            {
+               case NOT_PROTECTED -> null;
+               case HAS_ACCESS_PERMISSION -> PrivatePermissionSubType.HAS_ACCESS;
+               case READ_WRITE_PERMISSIONS ->
+               {
+                  if(PrivatePermissionSubType.READ.equals(originalPermissionSubType) || PrivatePermissionSubType.WRITE.equals(originalPermissionSubType))
+                  {
+                     yield (originalPermissionSubType);
+                  }
+                  else if(TablePermissionSubType.INSERT.equals(originalPermissionSubType) || TablePermissionSubType.EDIT.equals(originalPermissionSubType) || TablePermissionSubType.DELETE.equals(originalPermissionSubType))
+                  {
+                     yield (PrivatePermissionSubType.WRITE);
+                  }
+                  else if(TablePermissionSubType.READ.equals(originalPermissionSubType))
+                  {
+                     yield (PrivatePermissionSubType.READ);
+                  }
+                  else
+                  {
+                     throw new IllegalStateException("Unexpected permissionSubType: " + originalPermissionSubType);
+                  }
+               }
+               case READ_INSERT_EDIT_DELETE_PERMISSIONS -> originalPermissionSubType;
+            };
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void commonCheckPermissionThrowing(QPermissionRules rules, PermissionSubType permissionSubType, String name) throws QPermissionDeniedException
+   {
+      PermissionSubType effectivePermissionSubType = getEffectivePermissionSubType(rules, permissionSubType);
+      String            permissionBaseName         = getEffectivePermissionBaseName(rules, name);
+
+      if(effectivePermissionSubType == null)
+      {
+         return;
+      }
+
+      if(!hasPermission(QContext.getQSession(), permissionBaseName, effectivePermissionSubType))
+      {
+         // LOG.debug("Throwing permission denied for: " + getPermissionName(permissionBaseName, effectivePermissionSubType) + " for " + QContext.getQSession().getUser());
+         throw (new QPermissionDeniedException("Permission denied."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String getPermissionName(String permissionBaseName, PermissionSubType permissionSubType)
+   {
+      return permissionBaseName + "." + permissionSubType.getPermissionSuffix();
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static PermissionCheckResult getPermissionDeniedCheckResult(QPermissionRules rules)
+   {
+      if(rules == null || rules.getDenyBehavior() == null || rules.getDenyBehavior().equals(DenyBehavior.HIDDEN))
+      {
+         return (PermissionCheckResult.DENY_HIDE);
+      }
+      else
+      {
+         return (PermissionCheckResult.DENY_DISABLE);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void warnAboutPermissionSubTypeForTables(PermissionSubType permissionSubType)
+   {
+      if(permissionSubType == null)
+      {
+         return;
+      }
+
+      if(permissionSubType == PrivatePermissionSubType.HAS_ACCESS)
+      {
+         LOG.warn("PermissionSubType.HAS_ACCESS should not be checked for a table");
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/PrivatePermissionSubType.java

@@ -0,0 +1,56 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+enum PrivatePermissionSubType implements PermissionSubType
+{
+   HAS_ACCESS("hasAccess"), // for processes, reports, etc - basically, not tables.
+   READ("read"), // for a table in read/write mode - or - for read (query, get, count) on a table in full-mode
+   WRITE("write");
+
+   private final String permissionSuffix;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   PrivatePermissionSubType(String permissionSuffix)
+   {
+      this.permissionSuffix = permissionSuffix;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for permissionSuffix
+    *******************************************************************************/
+   public String getPermissionSuffix()
+   {
+      return (this.permissionSuffix);
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/ReportProcessPermissionChecker.java

@@ -0,0 +1,53 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ReportProcessPermissionChecker implements CustomPermissionChecker
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void checkPermissionsThrowing(AbstractActionInput actionInput, MetaDataWithPermissionRules metaDataWithPermissionRules) throws QPermissionDeniedException
+   {
+      if(actionInput instanceof RunProcessInput runProcessInput)
+      {
+         String reportName = runProcessInput.getValueString("reportName");
+         if(reportName != null)
+         {
+            PermissionsHelper.checkReportPermissionThrowing(actionInput, reportName);
+         }
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/permissions/TablePermissionSubType.java

@@ -0,0 +1,57 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.permissions;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public enum TablePermissionSubType implements PermissionSubType
+{
+   READ("read"), // for a table in read/write mode - or - for read (query, get, count) on a table in full-mode
+   INSERT("insert"), // for table-insert.
+   EDIT("edit"), // for table-edit.
+   DELETE("delete"); // for table-delete.
+
+   private final String permissionSuffix;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   TablePermissionSubType(String permissionSuffix)
+   {
+      this.permissionSuffix = permissionSuffix;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for permissionSuffix
+    *******************************************************************************/
+   public String getPermissionSuffix()
+   {
+      return (this.permissionSuffix);
+   }
+
+}

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

@@ -31,6 +31,7 @@ import com.kingsrook.qqq.backend.core.actions.ActionHelper;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
@@ -42,8 +43,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.processes.QFunctionInputMet
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -52,7 +51,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class RunBackendStepAction
 {
-   private static final Logger LOG = LogManager.getLogger(RunBackendStepAction.class);
+   private static final QLogger LOG = QLogger.getLogger(RunBackendStepAction.class);
 
 
 
@@ -107,7 +106,7 @@ public class RunBackendStepAction
          return;
       }
 
-      List<QFieldMetaData> fieldsToGet = new ArrayList<>();
+      List<QFieldMetaData> fieldsToGet           = new ArrayList<>();
       List<QFieldMetaData> requiredFieldsMissing = new ArrayList<>();
       for(QFieldMetaData field : inputMetaData.getFieldList())
       {
@@ -175,8 +174,7 @@ public class RunBackendStepAction
       {
          if(CollectionUtils.nullSafeIsEmpty(runBackendStepInput.getRecords()))
          {
-            QueryInput queryInput = new QueryInput(runBackendStepInput.getInstance());
-            queryInput.setSession(runBackendStepInput.getSession());
+            QueryInput queryInput = new QueryInput();
             queryInput.setTableName(inputMetaData.getRecordListMetaData().getTableName());
 
             // todo - handle this being async (e.g., http)

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

@@ -31,10 +31,13 @@ import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.NoCodeWidgetRenderer;
 import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessState;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
@@ -48,20 +51,24 @@ 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.actions.tables.update.UpdateInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.NoCodeWidgetFrontendComponentMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+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.QStepMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
 import com.kingsrook.qqq.backend.core.processes.implementations.basepull.BasepullConfiguration;
 import com.kingsrook.qqq.backend.core.state.InMemoryStateProvider;
 import com.kingsrook.qqq.backend.core.state.StateProviderInterface;
 import com.kingsrook.qqq.backend.core.state.StateType;
 import com.kingsrook.qqq.backend.core.state.UUIDAndTypeStateKey;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 import org.apache.commons.lang.BooleanUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -70,7 +77,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class RunProcessAction
 {
-   private static final Logger LOG = LogManager.getLogger(RunProcessAction.class);
+   private static final QLogger LOG = QLogger.getLogger(RunProcessAction.class);
 
    public static final String BASEPULL_THIS_RUNTIME_KEY = "basepullThisRuntimeKey";
    public static final String BASEPULL_LAST_RUNTIME_KEY = "basepullLastRuntimeKey";
@@ -80,6 +87,7 @@ public class RunProcessAction
    // indicator that the timestamp field should be updated - e.g., the execute step is finished. //
    ////////////////////////////////////////////////////////////////////////////////////////////////
    public static final String BASEPULL_READY_TO_UPDATE_TIMESTAMP_FIELD = "basepullReadyToUpdateTimestamp";
+   public static final String BASEPULL_DID_QUERY_USING_TIMESTAMP_FIELD = "basepullDidQueryUsingTimestamp";
 
 
 
@@ -142,7 +150,7 @@ public class RunProcessAction
             QStepMetaData step = stepList.get(0);
             lastStepName = step.getName();
 
-            if(step instanceof QFrontendStepMetaData)
+            if(step instanceof QFrontendStepMetaData frontendStep)
             {
                ////////////////////////////////////////////////////////////////
                // Handle what to do with frontend steps, per request setting //
@@ -152,6 +160,8 @@ public class RunProcessAction
                   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;
                   }
@@ -190,11 +200,14 @@ public class RunProcessAction
             }
          }
 
-         ////////////////////////////////////////////////////////////////////////////////////
-         // if 'basepull' style process, update the stored basepull timestamp              //
-         // but only when we've been signaled to do so - i.e., after an Execute step runs. //
-         ////////////////////////////////////////////////////////////////////////////////////
-         if(basepullConfiguration != null && BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(runProcessInput.getValue(BASEPULL_READY_TO_UPDATE_TIMESTAMP_FIELD))))
+         ///////////////////////////////////////////////////////////////////////////
+         // if 'basepull' style process, update the stored basepull timestamp     //
+         // but only when we've been signaled to do so - i.e., only if we did our //
+         // query using the timestamp field, and only after an Execute step runs. //
+         ///////////////////////////////////////////////////////////////////////////
+         if(basepullConfiguration != null
+            && BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(runProcessInput.getValue(BASEPULL_DID_QUERY_USING_TIMESTAMP_FIELD)))
+            && BooleanUtils.isTrue(ValueUtils.getValueAsBoolean(runProcessInput.getValue(BASEPULL_READY_TO_UPDATE_TIMESTAMP_FIELD))))
          {
             storeLastRunTime(runProcessInput, process, basepullConfiguration);
          }
@@ -226,6 +239,42 @@ public class RunProcessAction
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void processFrontendComponents(ProcessState processState, QFrontendStepMetaData frontendStep) throws QException
+   {
+      for(QFrontendComponentMetaData component : CollectionUtils.nonNullList(frontendStep.getComponents()))
+      {
+         if(component instanceof NoCodeWidgetFrontendComponentMetaData noCodeWidgetComponent)
+         {
+            NoCodeWidgetRenderer noCodeWidgetRenderer = new NoCodeWidgetRenderer();
+            Map<String, Object>  context              = noCodeWidgetRenderer.initContext(null);
+            context.putAll(processState.getValues());
+            String html = noCodeWidgetRenderer.renderOutputs(context, noCodeWidgetComponent.getOutputs());
+            processState.getValues().put(frontendStep.getName() + ".html", html);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void processFrontendStepFieldDefaultValues(ProcessState processState, QFrontendStepMetaData step)
+   {
+      for(QFieldMetaData formField : CollectionUtils.mergeLists(step.getFormFields(), step.getInputFields(), step.getViewFields(), step.getOutputFields()))
+      {
+         if(formField.getDefaultValue() != null && processState.getValues().get(formField.getName()) == null)
+         {
+            processState.getValues().put(formField.getName(), formField.getDefaultValue());
+         }
+      }
+   }
+
+
+
    /*******************************************************************************
     ** When we start running a process (or resuming it), get data in the RunProcessRequest
     ** either from the state provider (if they're found, for a resume).
@@ -291,15 +340,25 @@ public class RunProcessAction
     *******************************************************************************/
    private void runBackendStep(RunProcessInput runProcessInput, QProcessMetaData process, RunProcessOutput runProcessOutput, UUIDAndTypeStateKey stateKey, QBackendStepMetaData backendStep, QProcessMetaData qProcessMetaData, ProcessState processState) throws Exception
    {
-      RunBackendStepInput runBackendStepInput = new RunBackendStepInput(runProcessInput.getInstance(), processState);
+      RunBackendStepInput runBackendStepInput = new RunBackendStepInput(processState);
       runBackendStepInput.setProcessName(process.getName());
       runBackendStepInput.setStepName(backendStep.getName());
-      runBackendStepInput.setTableName(process.getTableName());
-      runBackendStepInput.setSession(runProcessInput.getSession());
       runBackendStepInput.setCallback(runProcessInput.getCallback());
       runBackendStepInput.setFrontendStepBehavior(runProcessInput.getFrontendStepBehavior());
       runBackendStepInput.setAsyncJobCallback(runProcessInput.getAsyncJobCallback());
 
+      runBackendStepInput.setTableName(process.getTableName());
+      if(!StringUtils.hasContent(runBackendStepInput.getTableName()))
+      {
+         ////////////////////////////////////////////////////////////////
+         // help support generic (e.g., not tied-to-a-table) processes //
+         ////////////////////////////////////////////////////////////////
+         if(runProcessInput.getValue("tableName") != null)
+         {
+            runBackendStepInput.setTableName(ValueUtils.getValueAsString(runProcessInput.getValue("tableName")));
+         }
+      }
+
       ///////////////////////////////////////////////////////////////
       // if 'basepull' values are in the inputs, add to step input //
       ///////////////////////////////////////////////////////////////
@@ -427,6 +486,35 @@ public class RunProcessAction
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   protected String determineBasepullKeyValue(QProcessMetaData process, BasepullConfiguration basepullConfiguration) throws QException
+   {
+      String basepullKeyValue = (basepullConfiguration.getKeyValue() != null) ? basepullConfiguration.getKeyValue() : process.getName();
+
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // if backend specifies that it uses variants, look for that data in the session and append to our basepull key //
+      //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      if(process.getSchedule() != null && process.getSchedule().getVariantBackend() != null)
+      {
+         QSession         session         = QContext.getQSession();
+         QBackendMetaData backendMetaData = QContext.getQInstance().getBackend(process.getSchedule().getVariantBackend());
+         if(session.getBackendVariants() == null || !session.getBackendVariants().containsKey(backendMetaData.getVariantOptionsTableTypeValue()))
+         {
+            LOG.info("Could not find Backend Variant information for Backend '" + backendMetaData.getName() + "'");
+         }
+         else
+         {
+            basepullKeyValue += "-" + session.getBackendVariants().get(backendMetaData.getVariantOptionsTableTypeValue());
+         }
+      }
+
+      return (basepullKeyValue);
+   }
+
+
+
    /*******************************************************************************
     ** Insert or update the last runtime value for this basepull into the backend.
     *******************************************************************************/
@@ -435,13 +523,12 @@ public class RunProcessAction
       String basepullTableName            = basepullConfiguration.getTableName();
       String basepullKeyFieldName         = basepullConfiguration.getKeyField();
       String basepullLastRunTimeFieldName = basepullConfiguration.getLastRunTimeFieldName();
-      String basepullKeyValue             = (basepullConfiguration.getKeyValue() != null) ? basepullConfiguration.getKeyValue() : process.getName();
+      String basepullKeyValue             = determineBasepullKeyValue(process, basepullConfiguration);
 
       ///////////////////////////////////////
       // get the stored basepull timestamp //
       ///////////////////////////////////////
-      QueryInput queryInput = new QueryInput(runProcessInput.getInstance());
-      queryInput.setSession(runProcessInput.getSession());
+      QueryInput queryInput = new QueryInput();
       queryInput.setTableName(basepullTableName);
       queryInput.setFilter(new QQueryFilter().withCriteria(
          new QFilterCriteria()
@@ -469,8 +556,7 @@ public class RunProcessAction
          ////////////
          // update //
          ////////////
-         UpdateInput updateInput = new UpdateInput(runProcessInput.getInstance());
-         updateInput.setSession(runProcessInput.getSession());
+         UpdateInput updateInput = new UpdateInput();
          updateInput.setTableName(basepullTableName);
          updateInput.setRecords(List.of(basepullRecord));
          new UpdateAction().execute(updateInput);
@@ -484,8 +570,7 @@ public class RunProcessAction
          ////////////////////////////////
          // insert new basepull record //
          ////////////////////////////////
-         InsertInput insertInput = new InsertInput(runProcessInput.getInstance());
-         insertInput.setSession(runProcessInput.getSession());
+         InsertInput insertInput = new InsertInput();
          insertInput.setTableName(basepullTableName);
          insertInput.setRecords(List.of(basepullRecord));
          new InsertAction().execute(insertInput);
@@ -518,13 +603,12 @@ public class RunProcessAction
       String  basepullKeyFieldName                 = basepullConfiguration.getKeyField();
       String  basepullLastRunTimeFieldName         = basepullConfiguration.getLastRunTimeFieldName();
       Integer basepullHoursBackForInitialTimestamp = basepullConfiguration.getHoursBackForInitialTimestamp();
-      String  basepullKeyValue                     = (basepullConfiguration.getKeyValue() != null) ? basepullConfiguration.getKeyValue() : process.getName();
+      String  basepullKeyValue                     = determineBasepullKeyValue(process, basepullConfiguration);
 
       ///////////////////////////////////////
       // get the stored basepull timestamp //
       ///////////////////////////////////////
-      QueryInput queryInput = new QueryInput(runProcessInput.getInstance());
-      queryInput.setSession(runProcessInput.getSession());
+      QueryInput queryInput = new QueryInput();
       queryInput.setTableName(basepullTableName);
       queryInput.setFilter(new QQueryFilter().withCriteria(
          new QFilterCriteria()

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/queues/GetQueueSize.java

@@ -0,0 +1,84 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.queues;
+
+
+import java.util.List;
+import com.amazonaws.auth.AWSStaticCredentialsProvider;
+import com.amazonaws.auth.BasicAWSCredentials;
+import com.amazonaws.services.sqs.AmazonSQS;
+import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
+import com.amazonaws.services.sqs.model.GetQueueAttributesResult;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.queues.QQueueMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.queues.QQueueProviderMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.queues.SQSQueueProviderMetaData;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class GetQueueSize
+{
+   private static final QLogger LOG = QLogger.getLogger(GetQueueSize.class);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public Integer getQueueSize(QQueueProviderMetaData queueProviderMetaData, QQueueMetaData queueMetaData) throws QException
+   {
+      try
+      {
+         //////////////////////////////////////////////////////////////////
+         // todo - handle other queue provider types, somewhere, somehow //
+         //////////////////////////////////////////////////////////////////
+         SQSQueueProviderMetaData queueProvider = (SQSQueueProviderMetaData) queueProviderMetaData;
+
+         BasicAWSCredentials credentials = new BasicAWSCredentials(queueProvider.getAccessKey(), queueProvider.getSecretKey());
+         final AmazonSQS sqs = AmazonSQSClientBuilder.standard()
+            .withRegion(queueProvider.getRegion())
+            .withCredentials(new AWSStaticCredentialsProvider(credentials))
+            .build();
+
+         String queueUrl = queueProvider.getBaseURL();
+         if(!queueUrl.endsWith("/"))
+         {
+            queueUrl += "/";
+         }
+         queueUrl += queueMetaData.getQueueName();
+
+         GetQueueAttributesResult queueAttributes             = sqs.getQueueAttributes(queueUrl, List.of("ApproximateNumberOfMessages"));
+         String                   approximateNumberOfMessages = queueAttributes.getAttributes().get("ApproximateNumberOfMessages");
+         return (Integer.parseInt(approximateNumberOfMessages));
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error getting queue size", e, logPair("queueName", queueMetaData == null ? "null" : queueMetaData.getName()));
+         throw (new QException("Error getting queue size", e));
+      }
+   }
+
+}

qqq-backend-core/src/main/java/com/kingsrook/qqq/backend/core/actions/queues/SQSQueuePoller.java

@@ -22,25 +22,27 @@
 package com.kingsrook.qqq.backend.core.actions.queues;
 
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.function.Supplier;
 import com.amazonaws.auth.AWSStaticCredentialsProvider;
 import com.amazonaws.auth.BasicAWSCredentials;
 import com.amazonaws.services.sqs.AmazonSQS;
 import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
-import com.amazonaws.services.sqs.model.DeleteMessageRequest;
+import com.amazonaws.services.sqs.model.DeleteMessageBatchRequest;
+import com.amazonaws.services.sqs.model.DeleteMessageBatchRequestEntry;
 import com.amazonaws.services.sqs.model.Message;
 import com.amazonaws.services.sqs.model.ReceiveMessageRequest;
 import com.amazonaws.services.sqs.model.ReceiveMessageResult;
 import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.queues.QQueueMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.queues.SQSQueueProviderMetaData;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
-import com.kingsrook.qqq.backend.core.scheduler.StandardScheduledExecutor;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -48,7 +50,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class SQSQueuePoller implements Runnable
 {
-   private static final Logger LOG = LogManager.getLogger(SQSQueuePoller.class);
+   private static final QLogger LOG = QLogger.getLogger(SQSQueuePoller.class);
 
    ///////////////////////////////////////////////
    // todo - move these 2 to a "QBaseRunnable"? //
@@ -67,8 +69,10 @@ public class SQSQueuePoller implements Runnable
    @Override
    public void run()
    {
+      QContext.init(qInstance, sessionSupplier.get());
+
       String originalThreadName = Thread.currentThread().getName();
-      Thread.currentThread().setName("SQSPoller>" + queueMetaData.getName() + StandardScheduledExecutor.newThreadNameRandomSuffix());
+      Thread.currentThread().setName("SQSPoller>" + queueMetaData.getName());
       LOG.debug("Running " + this.getClass().getSimpleName() + "[" + queueMetaData.getName() + "]");
 
       try
@@ -88,8 +92,13 @@ public class SQSQueuePoller implements Runnable
 
          while(true)
          {
+            ///////////////////////////////
+            // fetch a batch of messages //
+            ///////////////////////////////
             ReceiveMessageRequest receiveMessageRequest = new ReceiveMessageRequest();
             receiveMessageRequest.setQueueUrl(queueUrl);
+            receiveMessageRequest.setMaxNumberOfMessages(10);
+            receiveMessageRequest.setWaitTimeSeconds(20); // help urge SQS to query multiple servers and find more messages
             ReceiveMessageResult receiveMessageResult = sqs.receiveMessage(receiveMessageRequest);
             if(receiveMessageResult.getMessages().isEmpty())
             {
@@ -98,35 +107,71 @@ public class SQSQueuePoller implements Runnable
             }
             LOG.debug(receiveMessageResult.getMessages().size() + " messages received.  Processing.");
 
+            //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            // extract data from the messages into list of bodies to pass into process, and list of delete-batch-inputs //
+            //////////////////////////////////////////////////////////////////////////////////////////////////////////////
+            List<DeleteMessageBatchRequestEntry> deleteRequestEntries = new ArrayList<>();
+            ArrayList<String>                    bodies               = new ArrayList<>();
+            int                                  i                    = 0;
             for(Message message : receiveMessageResult.getMessages())
             {
-               String body = message.getBody();
+               bodies.add(message.getBody());
+               deleteRequestEntries.add(new DeleteMessageBatchRequestEntry(String.valueOf(i++), message.getReceiptHandle()));
+            }
 
-               RunProcessInput runProcessInput = new RunProcessInput(qInstance);
-               runProcessInput.setSession(sessionSupplier.get());
+            /////////////////////////////////////////////////////////////////////////////////////
+            // run the process, in a try-catch, so even if it fails, our loop keeps going.     //
+            // the messages in a failed process will get re-delivered, to try-again, up to the //
+            // number of times configured in AWS                                               //
+            /////////////////////////////////////////////////////////////////////////////////////
+            try
+            {
+               RunProcessInput runProcessInput = new RunProcessInput();
                runProcessInput.setProcessName(queueMetaData.getProcessName());
                runProcessInput.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP);
-               runProcessInput.addValue("body", body);
+               runProcessInput.addValue("bodies", bodies);
+
+               QContext.pushAction(runProcessInput);
 
                RunProcessAction runProcessAction = new RunProcessAction();
                RunProcessOutput runProcessOutput = runProcessAction.execute(runProcessInput);
 
-               /////////////////////////////////
-               // todo - what of exceptions?? //
-               /////////////////////////////////
-
-               String receiptHandle = message.getReceiptHandle();
-               sqs.deleteMessage(new DeleteMessageRequest(queueUrl, receiptHandle));
+               ////////////////////////////////////////////////////////////////////////////////////////////
+               // if there was an exception returned by the process (e.g., thrown in backend step), then //
+               // warn and leave the messages for re-processing.                                         //
+               ////////////////////////////////////////////////////////////////////////////////////////////
+               if(runProcessOutput.getException().isPresent())
+               {
+                  LOG.warn("Exception returned by process when handling SQS Messages.  They will not be deleted from the queue.", runProcessOutput.getException().get());
+               }
+               else
+               {
+                  ///////////////////////////////////////////////
+                  // else, if no exception, do a batch delete. //
+                  ///////////////////////////////////////////////
+                  sqs.deleteMessageBatch(new DeleteMessageBatchRequest()
+                     .withQueueUrl(queueUrl)
+                     .withEntries(deleteRequestEntries));
+               }
+            }
+            catch(Exception e)
+            {
+               LOG.warn("Error receiving SQS Messages.", e);
+            }
+            finally
+            {
+               QContext.popAction();
             }
          }
       }
       catch(Exception e)
       {
-         LOG.warn("Error receiving SQS Message", e);
+         LOG.warn("Error running SQS Queue Poller", e);
       }
       finally
       {
          Thread.currentThread().setName(originalThreadName);
+         QContext.clear();
       }
    }
 

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

@@ -0,0 +1,90 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Subclass of RecordPipe, which uses a buffer in the addRecord method, to avoid
+ ** sending single-records at a time through postRecordActions and to consumers.
+ *******************************************************************************/
+public class BufferedRecordPipe extends RecordPipe
+{
+   private List<QRecord> buffer     = new ArrayList<>();
+   private Integer       bufferSize = 100;
+
+
+
+   /*******************************************************************************
+    ** Constructor - uses default buffer size
+    **
+    *******************************************************************************/
+   public BufferedRecordPipe()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor - customize buffer size.
+    **
+    *******************************************************************************/
+   public BufferedRecordPipe(Integer bufferSize)
+   {
+      this.bufferSize = bufferSize;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void addRecord(QRecord record) throws QException
+   {
+      buffer.add(record);
+      if(buffer.size() >= bufferSize)
+      {
+         addRecords(buffer);
+         buffer.clear();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void finalFlush() throws QException
+   {
+      if(!buffer.isEmpty())
+      {
+         addRecords(buffer);
+         buffer.clear();
+      }
+   }
+}

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

@@ -27,13 +27,12 @@ import java.nio.charset.StandardCharsets;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.adapters.QRecordToCsvAdapter;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
 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;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -41,7 +40,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class CsvExportStreamer implements ExportStreamerInterface
 {
-   private static final Logger LOG = LogManager.getLogger(CsvExportStreamer.class);
+   private static final QLogger LOG = QLogger.getLogger(CsvExportStreamer.class);
 
    private final QRecordToCsvAdapter qRecordToCsvAdapter;
 

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

@@ -37,6 +37,7 @@ import java.util.Objects;
 import com.kingsrook.qqq.backend.core.actions.reporting.excelformatting.ExcelStylerInterface;
 import com.kingsrook.qqq.backend.core.actions.reporting.excelformatting.PlainExcelStyler;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
@@ -45,8 +46,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import com.kingsrook.qqq.backend.core.utils.ValueUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 import org.dhatim.fastexcel.StyleSetter;
 import org.dhatim.fastexcel.Workbook;
 import org.dhatim.fastexcel.Worksheet;
@@ -57,7 +56,7 @@ import org.dhatim.fastexcel.Worksheet;
  *******************************************************************************/
 public class ExcelExportStreamer implements ExportStreamerInterface
 {
-   private static final Logger LOG = LogManager.getLogger(ExcelExportStreamer.class);
+   private static final QLogger LOG = QLogger.getLogger(ExcelExportStreamer.class);
 
    private ExportInput          exportInput;
    private QTableMetaData       table;
@@ -247,14 +246,6 @@ public class ExcelExportStreamer implements ExportStreamerInterface
       for(QFieldMetaData field : fields)
       {
          Serializable value = qRecord.getValue(field.getName());
-         if(field.getPossibleValueSourceName() != null)
-         {
-            String displayValue = qRecord.getDisplayValue(field.getName());
-            if(displayValue != null)
-            {
-               value = displayValue;
-            }
-         }
 
          if(value != null)
          {

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

@@ -23,34 +23,42 @@ package com.kingsrook.qqq.backend.core.actions.reporting;
 
 
 import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.TimeUnit;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncJobManager;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncJobState;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncJobStatus;
 import com.kingsrook.qqq.backend.core.actions.interfaces.CountInterface;
-import com.kingsrook.qqq.backend.core.actions.interfaces.QueryInterface;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
 import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportOutput;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportFormat;
 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.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.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.ExposedJoin;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 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.SleepUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -66,7 +74,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class ExportAction
 {
-   private static final Logger LOG = LogManager.getLogger(ExportAction.class);
+   private static final QLogger LOG = QLogger.getLogger(ExportAction.class);
 
    private boolean preExecuteRan       = false;
    private Integer countFromPreExecute = null;
@@ -95,15 +103,25 @@ public class ExportAction
       ///////////////////////////////////
       if(CollectionUtils.nullSafeHasContents(exportInput.getFieldNames()))
       {
-         QTableMetaData table         = exportInput.getTable();
-         List<String>   badFieldNames = new ArrayList<>();
+         QTableMetaData              table        = exportInput.getTable();
+         Map<String, QTableMetaData> joinTableMap = getJoinTableMap(table);
+
+         List<String> badFieldNames = new ArrayList<>();
          for(String fieldName : exportInput.getFieldNames())
          {
             try
             {
-               table.getField(fieldName);
+               if(fieldName.contains("."))
+               {
+                  String[] parts = fieldName.split("\\.", 2);
+                  joinTableMap.get(parts[0]).getField(parts[1]);
+               }
+               else
+               {
+                  table.getField(fieldName);
+               }
             }
-            catch(IllegalArgumentException iae)
+            catch(Exception e)
             {
                badFieldNames.add(fieldName);
             }
@@ -128,6 +146,21 @@ public class ExportAction
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Map<String, QTableMetaData> getJoinTableMap(QTableMetaData table)
+   {
+      Map<String, QTableMetaData> joinTableMap = new HashMap<>();
+      for(ExposedJoin exposedJoin : CollectionUtils.nonNullList(table.getExposedJoins()))
+      {
+         joinTableMap.put(exposedJoin.getJoinTable(), QContext.getQInstance().getTable(exposedJoin.getJoinTable()));
+      }
+      return joinTableMap;
+   }
+
+
+
    /*******************************************************************************
     ** Run the report.
     *******************************************************************************/
@@ -147,17 +180,63 @@ public class ExportAction
       //////////////////////////
       // set up a query input //
       //////////////////////////
-      QueryInterface queryInterface = backendModule.getQueryInterface();
-      QueryInput     queryInput     = new QueryInput(exportInput.getInstance());
-      queryInput.setSession(exportInput.getSession());
+      QueryAction queryAction = new QueryAction();
+      QueryInput  queryInput  = new QueryInput();
       queryInput.setTableName(exportInput.getTableName());
       queryInput.setFilter(exportInput.getQueryFilter());
-      queryInput.setLimit(exportInput.getLimit());
+
+      List<QueryJoin> queryJoins     = new ArrayList<>();
+      Set<String>     addedJoinNames = new HashSet<>();
+      if(CollectionUtils.nullSafeHasContents(exportInput.getFieldNames()))
+      {
+         for(String fieldName : exportInput.getFieldNames())
+         {
+            if(fieldName.contains("."))
+            {
+               String[] parts         = fieldName.split("\\.", 2);
+               String   joinTableName = parts[0];
+               if(!addedJoinNames.contains(joinTableName))
+               {
+                  QueryJoin queryJoin = new QueryJoin(joinTableName).withType(QueryJoin.Type.LEFT).withSelect(true);
+                  queryJoins.add(queryJoin);
+
+                  /////////////////////////////////////////////////////////////////////////////////////////////
+                  // in at least some cases, we need to let the queryJoin know what join-meta-data to use... //
+                  // This code basically mirrors what QFMD is doing right now, so it's better -              //
+                  // but shouldn't all of this just be in JoinsContext?  it does some of this...             //
+                  /////////////////////////////////////////////////////////////////////////////////////////////
+                  QTableMetaData        table               = exportInput.getTable();
+                  Optional<ExposedJoin> exposedJoinOptional = CollectionUtils.nonNullList(table.getExposedJoins()).stream().filter(ej -> ej.getJoinTable().equals(joinTableName)).findFirst();
+                  if(exposedJoinOptional.isEmpty())
+                  {
+                     throw (new QException("Could not find exposed join between base table " + table.getName() + " and requested join table " + joinTableName));
+                  }
+                  ExposedJoin exposedJoin = exposedJoinOptional.get();
+
+                  if(exposedJoin.getJoinPath().size() == 1)
+                  {
+                     queryJoin.setJoinMetaData(QContext.getQInstance().getJoin(exposedJoin.getJoinPath().get(exposedJoin.getJoinPath().size() - 1)));
+                  }
+
+                  addedJoinNames.add(joinTableName);
+               }
+            }
+         }
+      }
+
+      queryInput.setQueryJoins(queryJoins);
+
+      if(queryInput.getFilter() == null)
+      {
+         queryInput.setFilter(new QQueryFilter());
+      }
+      queryInput.getFilter().setLimit(exportInput.getLimit());
+      queryInput.setShouldTranslatePossibleValues(true);
 
       /////////////////////////////////////////////////////////////////
       // tell this query that it needs to put its output into a pipe //
       /////////////////////////////////////////////////////////////////
-      RecordPipe recordPipe = new RecordPipe();
+      RecordPipe recordPipe = new BufferedRecordPipe(500);
       queryInput.setRecordPipe(recordPipe);
 
       ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -165,13 +244,14 @@ public class ExportAction
       ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
       ReportFormat            reportFormat   = exportInput.getReportFormat();
       ExportStreamerInterface reportStreamer = reportFormat.newReportStreamer();
-      reportStreamer.start(exportInput, getFields(exportInput), "Sheet 1");
+      List<QFieldMetaData>    fields         = getFields(exportInput);
+      reportStreamer.start(exportInput, fields, "Sheet 1");
 
       //////////////////////////////////////////
       // run the query action as an async job //
       //////////////////////////////////////////
       AsyncJobManager asyncJobManager = new AsyncJobManager();
-      String          queryJobUUID    = asyncJobManager.startJob("ReportAction>QueryAction", (status) -> (queryInterface.execute(queryInput)));
+      String          queryJobUUID    = asyncJobManager.startJob("ReportAction>QueryAction", (status) -> (queryAction.execute(queryInput)));
       LOG.info("Started query job [" + queryJobUUID + "] for report");
 
       AsyncJobState  queryJobState  = AsyncJobState.RUNNING;
@@ -209,7 +289,7 @@ public class ExportAction
             nextSleepMillis = INIT_SLEEP_MS;
 
             List<QRecord> records = recordPipe.consumeAvailableRecords();
-            reportStreamer.addRecords(records);
+            processRecords(reportStreamer, fields, records);
             recordCount += records.size();
 
             LOG.info(countFromPreExecute != null
@@ -238,7 +318,7 @@ public class ExportAction
       // send the final records to the report streamer //
       ///////////////////////////////////////////////////
       List<QRecord> records = recordPipe.consumeAvailableRecords();
-      reportStreamer.addRecords(records);
+      processRecords(reportStreamer, fields, records);
       recordCount += records.size();
 
       long reportEndTime = System.currentTimeMillis();
@@ -269,20 +349,86 @@ public class ExportAction
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void processRecords(ExportStreamerInterface reportStreamer, List<QFieldMetaData> fields, List<QRecord> records) throws QReportingException
+   {
+      for(QFieldMetaData field : fields)
+      {
+         if(field.getName().endsWith(":possibleValueLabel"))
+         {
+            String effectiveFieldName = field.getName().replace(":possibleValueLabel", "");
+            for(QRecord record : records)
+            {
+               String displayValue = record.getDisplayValue(effectiveFieldName);
+               record.setValue(field.getName(), displayValue);
+            }
+         }
+      }
+
+      reportStreamer.addRecords(records);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
    private List<QFieldMetaData> getFields(ExportInput exportInput)
    {
-      QTableMetaData table = exportInput.getTable();
+      QTableMetaData              table        = exportInput.getTable();
+      Map<String, QTableMetaData> joinTableMap = getJoinTableMap(table);
+
+      List<QFieldMetaData> fieldList;
       if(exportInput.getFieldNames() != null)
       {
-         return (exportInput.getFieldNames().stream().map(table::getField).toList());
+         fieldList = new ArrayList<>();
+         for(String fieldName : exportInput.getFieldNames())
+         {
+            if(fieldName.contains("."))
+            {
+               String[]       parts     = fieldName.split("\\.", 2);
+               QTableMetaData joinTable = joinTableMap.get(parts[0]);
+               QFieldMetaData field     = joinTable.getField(parts[1]).clone();
+               field.setName(fieldName);
+               field.setLabel(joinTable.getLabel() + ": " + field.getLabel());
+               fieldList.add(field);
+            }
+            else
+            {
+               fieldList.add(table.getField(fieldName));
+            }
+         }
       }
       else
       {
-         return (new ArrayList<>(table.getFields().values()));
+         fieldList = new ArrayList<>(table.getFields().values());
       }
+
+      List<QFieldMetaData> returnList = new ArrayList<>();
+      for(QFieldMetaData field : fieldList)
+      {
+         /////////////////////////////////////////////////////////////////////////////////////////
+         // skip heavy fields.  they aren't fetched, and we generally think we don't want them. //
+         /////////////////////////////////////////////////////////////////////////////////////////
+         if(field.getIsHeavy())
+         {
+            continue;
+         }
+
+         returnList.add(field);
+
+         //////////////////////////////////////////
+         // add fields for possible value labels //
+         //////////////////////////////////////////
+         if(StringUtils.hasContent(field.getPossibleValueSourceName()))
+         {
+            returnList.add(new QFieldMetaData(field.getName() + ":possibleValueLabel", QFieldType.STRING).withLabel(field.getLabel() + " Name"));
+         }
+      }
+
+      return (returnList);
    }
 
 
@@ -308,8 +454,7 @@ public class ExportAction
          if(exportInput.getLimit() == null || exportInput.getLimit() > reportFormat.getMaxRows())
          {
             CountInterface countInterface = backendModule.getCountInterface();
-            CountInput     countInput     = new CountInput(exportInput.getInstance());
-            countInput.setSession(exportInput.getSession());
+            CountInput     countInput     = new CountInput();
             countInput.setTableName(exportInput.getTableName());
             countInput.setFilter(exportInput.getQueryFilter());
             CountOutput countOutput = countInterface.execute(countInput);

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

@@ -185,7 +185,7 @@ public class FormulaInterpreter
          case "DIVIDE":
          {
             List<BigDecimal> numbers = getNumberArgumentList(args, 2, variableInterpreter);
-            if(numbers.get(1) == null || numbers.get(1).equals(BigDecimal.ZERO))
+            if(numbers.get(1) == null || numbers.get(1).compareTo(BigDecimal.ZERO) == 0)
             {
                return null;
             }
@@ -194,7 +194,7 @@ public class FormulaInterpreter
          case "DIVIDE_SCALE":
          {
             List<BigDecimal> numbers = getNumberArgumentList(args, 3, variableInterpreter);
-            if(numbers.get(1) == null || numbers.get(1).equals(BigDecimal.ZERO))
+            if(numbers.get(1) == null || numbers.get(1).compareTo(BigDecimal.ZERO) == 0)
             {
                return null;
             }

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

@@ -27,13 +27,17 @@ import java.math.BigDecimal;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import com.kingsrook.qqq.backend.core.actions.async.AsyncRecordPipeLoop;
 import com.kingsrook.qqq.backend.core.actions.customizers.QCodeLoader;
+import com.kingsrook.qqq.backend.core.actions.reporting.customizers.DataSourceQueryInputCustomizer;
 import com.kingsrook.qqq.backend.core.actions.reporting.customizers.ReportViewCustomizer;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.values.QValueFormatter;
@@ -41,13 +45,13 @@ import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QFormulaException;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
 import com.kingsrook.qqq.backend.core.instances.QMetaDataVariableInterpreter;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportFormat;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ReportInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.JoinsContext;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
@@ -61,10 +65,11 @@ import com.kingsrook.qqq.backend.core.model.metadata.reporting.QReportView;
 import com.kingsrook.qqq.backend.core.model.metadata.reporting.ReportType;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.BackendStepPostRunInput;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.BackendStepPostRunOutput;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.Pair;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
-import com.kingsrook.qqq.backend.core.utils.ValueUtils;
 import com.kingsrook.qqq.backend.core.utils.aggregates.AggregatesInterface;
 import com.kingsrook.qqq.backend.core.utils.aggregates.BigDecimalAggregates;
 import com.kingsrook.qqq.backend.core.utils.aggregates.IntegerAggregates;
@@ -84,6 +89,8 @@ import com.kingsrook.qqq.backend.core.utils.aggregates.IntegerAggregates;
  *******************************************************************************/
 public class GenerateReportAction
 {
+   private static final QLogger LOG = QLogger.getLogger(GenerateReportAction.class);
+
    /////////////////////////////////////////////////////////////////////////////////////////////////////////////
    // summaryAggregates and varianceAggregates are multi-level maps, ala:                                     //
    // viewName > SummaryKey > fieldName > Aggregates                                                          //
@@ -113,6 +120,10 @@ public class GenerateReportAction
    {
       report = reportInput.getInstance().getReport(reportInput.getReportName());
       reportFormat = reportInput.getReportFormat();
+      if(reportFormat == null)
+      {
+         throw new QException("Report format was not specified.");
+      }
       reportStreamer = reportFormat.newReportStreamer();
 
       ////////////////////////////////////////////////////////////////////////////////////////////////
@@ -179,6 +190,17 @@ public class GenerateReportAction
       }
 
       outputSummaries(reportInput);
+
+      reportStreamer.finish();
+
+      try
+      {
+         reportInput.getReportOutputStream().close();
+      }
+      catch(Exception e)
+      {
+         throw (new QReportingException("Error completing report", e));
+      }
    }
 
 
@@ -193,48 +215,45 @@ public class GenerateReportAction
       QMetaDataVariableInterpreter variableInterpreter = new QMetaDataVariableInterpreter();
       variableInterpreter.addValueMap("input", reportInput.getInputValues());
 
-      ExportInput exportInput = new ExportInput(reportInput.getInstance());
-      exportInput.setSession(reportInput.getSession());
+      ExportInput exportInput = new ExportInput();
       exportInput.setReportFormat(reportFormat);
       exportInput.setFilename(reportInput.getFilename());
       exportInput.setTitleRow(getTitle(reportView, variableInterpreter));
       exportInput.setIncludeHeaderRow(reportView.getIncludeHeaderRow());
       exportInput.setReportOutputStream(reportInput.getReportOutputStream());
 
-      JoinsContext joinsContext = new JoinsContext(exportInput.getInstance(), dataSource.getSourceTable(), dataSource.getQueryJoins());
-
-      List<QFieldMetaData> fields;
-      if(CollectionUtils.nullSafeHasContents(reportView.getColumns()))
+      JoinsContext joinsContext = null;
+      if(StringUtils.hasContent(dataSource.getSourceTable()))
       {
-         fields = new ArrayList<>();
-         for(QReportField column : reportView.getColumns())
-         {
-            if(column.getIsVirtual())
-            {
-               fields.add(column.toField());
-            }
-            else
-            {
-               JoinsContext.FieldAndTableNameOrAlias fieldAndTableNameOrAlias = joinsContext.getFieldAndTableNameOrAlias(column.getName());
-               if(fieldAndTableNameOrAlias.field() == null)
-               {
-                  throw new QReportingException("Could not find field named [" + column.getName() + "] on table [" + table.getName() + "]");
-               }
+         joinsContext = new JoinsContext(exportInput.getInstance(), dataSource.getSourceTable(), dataSource.getQueryJoins(), dataSource.getQueryFilter());
+      }
 
-               QFieldMetaData field = fieldAndTableNameOrAlias.field().clone();
-               field.setName(column.getName());
-               if(StringUtils.hasContent(column.getLabel()))
-               {
-                  field.setLabel(column.getLabel());
-               }
-               fields.add(field);
+      List<QFieldMetaData> fields = new ArrayList<>();
+      for(QReportField column : reportView.getColumns())
+      {
+         if(column.getIsVirtual())
+         {
+            fields.add(column.toField());
+         }
+         else
+         {
+            String                                effectiveFieldName       = Objects.requireNonNullElse(column.getSourceFieldName(), column.getName());
+            JoinsContext.FieldAndTableNameOrAlias fieldAndTableNameOrAlias = joinsContext == null ? null : joinsContext.getFieldAndTableNameOrAlias(effectiveFieldName);
+            if(fieldAndTableNameOrAlias == null || fieldAndTableNameOrAlias.field() == null)
+            {
+               throw new QReportingException("Could not find field named [" + effectiveFieldName + "] in dataSource [" + dataSource.getName() + "]");
             }
+
+            QFieldMetaData field = fieldAndTableNameOrAlias.field().clone();
+            field.setName(column.getName());
+            if(StringUtils.hasContent(column.getLabel()))
+            {
+               field.setLabel(column.getLabel());
+            }
+            fields.add(field);
          }
       }
-      else
-      {
-         fields = new ArrayList<>(table.getFields().values());
-      }
+
       reportStreamer.setDisplayFormats(getDisplayFormatMap(fields));
       reportStreamer.start(exportInput, fields, reportView.getLabel());
    }
@@ -256,8 +275,7 @@ public class GenerateReportAction
       {
          transformStep = QCodeLoader.getBackendStep(AbstractTransformStep.class, tableView.getRecordTransformStep());
 
-         transformStepInput = new RunBackendStepInput(reportInput.getInstance());
-         transformStepInput.setSession(reportInput.getSession());
+         transformStepInput = new RunBackendStepInput();
          transformStepInput.setValues(reportInput.getInputValues());
 
          transformStepOutput = new RunBackendStepOutput();
@@ -275,21 +293,29 @@ public class GenerateReportAction
       /////////////////////////////////////////////////////////////////
       // run a record pipe loop, over the query for this data source //
       /////////////////////////////////////////////////////////////////
-      RecordPipe recordPipe = new RecordPipe();
+      RecordPipe recordPipe = new BufferedRecordPipe(1000);
       new AsyncRecordPipeLoop().run("Report[" + reportInput.getReportName() + "]", null, recordPipe, (callback) ->
       {
          if(dataSource.getSourceTable() != null)
          {
-            QQueryFilter queryFilter = dataSource.getQueryFilter().clone();
+            QQueryFilter queryFilter = dataSource.getQueryFilter() == null ? new QQueryFilter() : dataSource.getQueryFilter().clone();
             setInputValuesInQueryFilter(reportInput, queryFilter);
 
-            QueryInput queryInput = new QueryInput(reportInput.getInstance());
-            queryInput.setSession(reportInput.getSession());
+            QueryInput queryInput = new QueryInput();
             queryInput.setRecordPipe(recordPipe);
             queryInput.setTableName(dataSource.getSourceTable());
             queryInput.setFilter(queryFilter);
             queryInput.setQueryJoins(dataSource.getQueryJoins());
-            queryInput.setShouldTranslatePossibleValues(true); // todo - any limits or conditions on this?
+
+            queryInput.setShouldTranslatePossibleValues(true);
+            queryInput.setFieldsToTranslatePossibleValues(setupFieldsToTranslatePossibleValues(reportInput, dataSource, new JoinsContext(reportInput.getInstance(), dataSource.getSourceTable(), dataSource.getQueryJoins(), queryInput.getFilter())));
+
+            if(dataSource.getQueryInputCustomizer() != null)
+            {
+               DataSourceQueryInputCustomizer queryInputCustomizer = QCodeLoader.getAdHoc(DataSourceQueryInputCustomizer.class, dataSource.getQueryInputCustomizer());
+               queryInput = queryInputCustomizer.run(reportInput, queryInput);
+            }
+
             return (new QueryAction().execute(queryInput));
          }
          else if(dataSource.getStaticDataSupplier() != null)
@@ -331,12 +357,51 @@ public class GenerateReportAction
       ////////////////////////////////////////////////
       if(transformStep != null)
       {
-         transformStep.postRun(transformStepInput, transformStepOutput);
+         transformStep.postRun(new BackendStepPostRunInput(transformStepInput), new BackendStepPostRunOutput(transformStepOutput));
       }
    }
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Set<String> setupFieldsToTranslatePossibleValues(ReportInput reportInput, QReportDataSource dataSource, JoinsContext joinsContext)
+   {
+      Set<String> fieldsToTranslatePossibleValues = new HashSet<>();
+
+      for(QReportView view : report.getViews())
+      {
+         for(QReportField column : CollectionUtils.nonNullList(view.getColumns()))
+         {
+            ////////////////////////////////////////////////////////////////////////////////////////
+            // if this is a column marked as ShowPossibleValueLabel, then we need to translate it //
+            ////////////////////////////////////////////////////////////////////////////////////////
+            if(column.getShowPossibleValueLabel())
+            {
+               String effectiveFieldName = Objects.requireNonNullElse(column.getSourceFieldName(), column.getName());
+               fieldsToTranslatePossibleValues.add(effectiveFieldName);
+            }
+         }
+
+         for(String summaryField : CollectionUtils.nonNullList(view.getPivotFields()))
+         {
+            ///////////////////////////////////////////////////////////////////////////////
+            // all pivotFields that are possible value sources are implicitly translated //
+            ///////////////////////////////////////////////////////////////////////////////
+            QTableMetaData table = reportInput.getInstance().getTable(dataSource.getSourceTable());
+            if(table.getField(summaryField).getPossibleValueSourceName() != null)
+            {
+               fieldsToTranslatePossibleValues.add(summaryField);
+            }
+         }
+      }
+
+      return (fieldsToTranslatePossibleValues);
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/
@@ -347,23 +412,7 @@ public class GenerateReportAction
          return;
       }
 
-      QMetaDataVariableInterpreter variableInterpreter = new QMetaDataVariableInterpreter();
-      variableInterpreter.addValueMap("input", reportInput.getInputValues());
-      for(QFilterCriteria criterion : queryFilter.getCriteria())
-      {
-         if(criterion.getValues() != null)
-         {
-            List<Serializable> newValues = new ArrayList<>();
-
-            for(Serializable value : criterion.getValues())
-            {
-               String       valueAsString    = ValueUtils.getValueAsString(value);
-               Serializable interpretedValue = variableInterpreter.interpret(valueAsString);
-               newValues.add(interpretedValue);
-            }
-            criterion.setValues(newValues);
-         }
-      }
+      queryFilter.interpretValues(reportInput.getInputValues());
    }
 
 
@@ -380,6 +429,22 @@ public class GenerateReportAction
       ////////////////////////////////////////////////////////////////////////////
       if(tableView != null)
       {
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if any fields are 'showPossibleValueLabel', then move display values for them into the record's values map //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         for(QReportField column : tableView.getColumns())
+         {
+            if(column.getShowPossibleValueLabel())
+            {
+               String effectiveFieldName = Objects.requireNonNullElse(column.getSourceFieldName(), column.getName());
+               for(QRecord record : records)
+               {
+                  String displayValue = record.getDisplayValue(effectiveFieldName);
+                  record.setValue(column.getName(), displayValue);
+               }
+            }
+         }
+
          reportStreamer.addRecords(records);
       }
 
@@ -441,6 +506,9 @@ public class GenerateReportAction
             Serializable summaryValue = record.getValue(summaryField);
             if(table.getField(summaryField).getPossibleValueSourceName() != null)
             {
+               //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+               // so, this is kinda a thing - where we implicitly use possible-value labels (e.g., display values) for pivot fields... //
+               //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
                summaryValue = record.getDisplayValue(summaryField);
             }
             key.add(summaryField, summaryValue);
@@ -509,8 +577,7 @@ public class GenerateReportAction
          QTableMetaData    table         = reportInput.getInstance().getTable(dataSource.getSourceTable());
          SummaryOutput     summaryOutput = computeSummaryRowsForView(reportInput, view, table);
 
-         ExportInput exportInput = new ExportInput(reportInput.getInstance());
-         exportInput.setSession(reportInput.getSession());
+         ExportInput exportInput = new ExportInput();
          exportInput.setReportFormat(reportFormat);
          exportInput.setFilename(reportInput.getFilename());
          exportInput.setTitleRow(summaryOutput.titleRow);
@@ -527,8 +594,6 @@ public class GenerateReportAction
             reportStreamer.addTotalsRow(summaryOutput.totalRow);
          }
       }
-
-      reportStreamer.finish();
    }
 
 

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

@@ -0,0 +1,177 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting;
+
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
+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;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** JSON export format implementation
+ *******************************************************************************/
+public class JsonExportStreamer implements ExportStreamerInterface
+{
+   private static final QLogger LOG = QLogger.getLogger(JsonExportStreamer.class);
+
+   private ExportInput          exportInput;
+   private QTableMetaData       table;
+   private List<QFieldMetaData> fields;
+   private OutputStream         outputStream;
+
+   private boolean needComma   = false;
+   private boolean prettyPrint = true;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public JsonExportStreamer()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void start(ExportInput exportInput, List<QFieldMetaData> fields, String label) throws QReportingException
+   {
+      this.exportInput = exportInput;
+      this.fields = fields;
+      table = exportInput.getTable();
+      outputStream = this.exportInput.getReportOutputStream();
+
+      try
+      {
+         outputStream.write('[');
+      }
+      catch(IOException e)
+      {
+         throw (new QReportingException("Error starting report output", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void addRecords(List<QRecord> qRecords) throws QReportingException
+   {
+      LOG.info("Consuming [" + qRecords.size() + "] records from the pipe");
+
+      for(QRecord qRecord : qRecords)
+      {
+         writeRecord(qRecord);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void writeRecord(QRecord qRecord) throws QReportingException
+   {
+      try
+      {
+         if(needComma)
+         {
+            outputStream.write(',');
+         }
+
+         Map<String, Serializable> mapForJson = new LinkedHashMap<>();
+         for(QFieldMetaData field : fields)
+         {
+            String labelForJson = StringUtils.lcFirst(field.getLabel().replace(" ", ""));
+            mapForJson.put(labelForJson, qRecord.getValue(field.getName()));
+         }
+
+         String json = prettyPrint ? JsonUtils.toPrettyJson(mapForJson) : JsonUtils.toJson(mapForJson);
+
+         if(prettyPrint)
+         {
+            outputStream.write('\n');
+         }
+
+         outputStream.write(json.getBytes(StandardCharsets.UTF_8));
+
+         outputStream.flush(); // todo - less often?
+         needComma = true;
+      }
+      catch(Exception e)
+      {
+         throw (new QReportingException("Error writing JSON report", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void addTotalsRow(QRecord record) throws QReportingException
+   {
+      writeRecord(record);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void finish() throws QReportingException
+   {
+      try
+      {
+         if(prettyPrint)
+         {
+            outputStream.write('\n');
+         }
+         outputStream.write(']');
+      }
+      catch(IOException e)
+      {
+         throw (new QReportingException("Error ending report output", e));
+      }
+   }
+
+}

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

@@ -27,11 +27,10 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import com.kingsrook.qqq.backend.core.exceptions.QReportingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.reporting.ExportInput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
 
 
 /*******************************************************************************
@@ -41,7 +40,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class ListOfMapsExportStreamer implements ExportStreamerInterface
 {
-   private static final Logger LOG = LogManager.getLogger(ListOfMapsExportStreamer.class);
+   private static final QLogger LOG = QLogger.getLogger(ListOfMapsExportStreamer.class);
 
    private ExportInput          exportInput;
    private List<QFieldMetaData> fields;

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

@@ -26,11 +26,11 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.ArrayBlockingQueue;
 import java.util.concurrent.TimeUnit;
-import java.util.function.Consumer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.utils.SleepUtils;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import com.kingsrook.qqq.backend.core.utils.lambdas.UnsafeConsumer;
 
 
 /*******************************************************************************
@@ -39,7 +39,7 @@ import org.apache.logging.log4j.Logger;
  *******************************************************************************/
 public class RecordPipe
 {
-   private static final Logger LOG = LogManager.getLogger(RecordPipe.class);
+   private static final QLogger LOG = QLogger.getLogger(RecordPipe.class);
 
    private static final long BLOCKING_SLEEP_MILLIS = 100;
    private static final long MAX_SLEEP_LOOP_MILLIS = 300_000; // 5 minutes
@@ -48,7 +48,7 @@ public class RecordPipe
 
    private boolean isTerminated = false;
 
-   private Consumer<List<QRecord>> postRecordActions = null;
+   private UnsafeConsumer<List<QRecord>, QException> postRecordActions = null;
 
    /////////////////////////////////////
    // See usage below for explanation //
@@ -94,7 +94,7 @@ public class RecordPipe
    /*******************************************************************************
     ** Add a record to the pipe.  Will block if the pipe is full.  Will noop if pipe is terminated.
     *******************************************************************************/
-   public void addRecord(QRecord record)
+   public void addRecord(QRecord record) throws QException
    {
       if(isTerminated)
       {
@@ -110,7 +110,7 @@ public class RecordPipe
          // (which we'll create as a field in this class, to avoid always re-constructing) //
          ////////////////////////////////////////////////////////////////////////////////////
          singleRecordListForPostRecordActions.add(record);
-         postRecordActions.accept(singleRecordListForPostRecordActions);
+         postRecordActions.run(singleRecordListForPostRecordActions);
          record = singleRecordListForPostRecordActions.remove(0);
       }
 
@@ -153,11 +153,11 @@ public class RecordPipe
    /*******************************************************************************
     ** Add a list of records to the pipe.  Will block if the pipe is full.  Will noop if pipe is terminated.
     *******************************************************************************/
-   public void addRecords(List<QRecord> records)
+   public void addRecords(List<QRecord> records) throws QException
    {
       if(postRecordActions != null)
       {
-         postRecordActions.accept(records);
+         postRecordActions.run(records);
       }
 
       //////////////////////////////////////////////////////////////////////////////////////////////////
@@ -208,7 +208,7 @@ public class RecordPipe
    /*******************************************************************************
     **
     *******************************************************************************/
-   public void setPostRecordActions(Consumer<List<QRecord>> postRecordActions)
+   public void setPostRecordActions(UnsafeConsumer<List<QRecord>, QException> postRecordActions)
    {
       this.postRecordActions = postRecordActions;
    }

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

@@ -0,0 +1,79 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Subclass of BufferedRecordPipe, which ultimately sends records down to an
+ ** original RecordPipe.
+ **
+ ** Meant to be used where: someone passed in a RecordPipe (so they have a reference
+ ** to it, and they are waiting to read from it), but the producer knows that
+ ** it will be better to buffer the records, so they want to use a buffered pipe
+ ** (but they still need the records to end up in the original pipe - thus -
+ ** it gets wrapped by an object of this class).
+ *******************************************************************************/
+public class RecordPipeBufferedWrapper extends BufferedRecordPipe
+{
+   private RecordPipe wrappedPipe;
+
+
+
+   /*******************************************************************************
+    ** Constructor - uses default buffer size
+    **
+    *******************************************************************************/
+   public RecordPipeBufferedWrapper(RecordPipe wrappedPipe)
+   {
+      this.wrappedPipe = wrappedPipe;
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor - customize buffer size.
+    **
+    *******************************************************************************/
+   public RecordPipeBufferedWrapper(Integer bufferSize, RecordPipe wrappedPipe)
+   {
+      super(bufferSize);
+      this.wrappedPipe = wrappedPipe;
+   }
+
+
+
+   /*******************************************************************************
+    ** when it's time to actually add records into the pipe, actually add them
+    ** into the wrapped pipe!
+    *******************************************************************************/
+   @Override
+   public void addRecords(List<QRecord> records) throws QException
+   {
+      wrappedPipe.addRecords(records);
+   }
+
+}

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

@@ -0,0 +1,45 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.reporting.customizers;
+
+
+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.actions.tables.query.QueryInput;
+
+
+/*******************************************************************************
+ ** Interface for customizer on a QReportDataSource's query.
+ **
+ ** Useful, for example, to look at what input field values were given, and change
+ ** the query filter (e.g., conditional criteria), or issue an error based on the
+ ** combination of input fields given.
+ *******************************************************************************/
+public interface DataSourceQueryInputCustomizer
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   QueryInput run(ReportInput reportInput, QueryInput queryInput) throws QException;
+
+}

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

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

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

@@ -23,15 +23,36 @@ package com.kingsrook.qqq.backend.core.actions.scripts;
 
 
 import java.io.Serializable;
+import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import com.kingsrook.qqq.backend.core.actions.scripts.logging.Log4jCodeExecutionLogger;
 import com.kingsrook.qqq.backend.core.actions.scripts.logging.QCodeExecutionLoggerInterface;
+import com.kingsrook.qqq.backend.core.actions.scripts.logging.ScriptExecutionLoggerInterface;
+import com.kingsrook.qqq.backend.core.actions.scripts.logging.StoreScriptLogAndScriptLogLineExecutionLogger;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QCodeException;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.AbstractRunScriptInput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeInput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeType;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevisionFile;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.ObjectUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
 
 /*******************************************************************************
@@ -49,6 +70,9 @@ import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
  *******************************************************************************/
 public class ExecuteCodeAction
 {
+   private static final QLogger LOG = QLogger.getLogger(ExecuteCodeAction.class);
+
+
 
    /*******************************************************************************
     **
@@ -68,10 +92,10 @@ public class ExecuteCodeAction
       try
       {
          String languageExecutor = switch(codeReference.getCodeType())
-            {
-               case JAVA -> "com.kingsrook.qqq.backend.core.actions.scripts.QJavaExecutor";
-               case JAVA_SCRIPT -> "com.kingsrook.qqq.languages.javascript.QJavaScriptExecutor";
-            };
+         {
+            case JAVA -> "com.kingsrook.qqq.backend.core.actions.scripts.QJavaExecutor";
+            case JAVA_SCRIPT -> "com.kingsrook.qqq.languages.javascript.QJavaScriptExecutor";
+         };
 
          @SuppressWarnings("unchecked")
          Class<? extends QCodeExecutor> executorClass = (Class<? extends QCodeExecutor>) Class.forName(languageExecutor);
@@ -90,6 +114,22 @@ public class ExecuteCodeAction
             context.putAll(input.getInput());
          }
 
+         //////////////////////////////////////////
+         // safely always set the deploymentMode //
+         //////////////////////////////////////////
+         context.put("deploymentMode", ObjectUtils.tryAndRequireNonNullElse(() -> QContext.getQInstance().getDeploymentMode(), null));
+
+         /////////////////////////////////////////////////////////////////////////////////
+         // set the qCodeExecutor into any context objects which are QCodeExecutorAware //
+         /////////////////////////////////////////////////////////////////////////////////
+         for(Serializable value : context.values())
+         {
+            if(value instanceof QCodeExecutorAware qCodeExecutorAware)
+            {
+               qCodeExecutorAware.setQCodeExecutor(qCodeExecutor);
+            }
+         }
+
          Serializable codeOutput = qCodeExecutor.execute(codeReference, context, executionLogger);
          output.setOutput(codeOutput);
          executionLogger.acceptExecutionEnd(codeOutput);
@@ -108,6 +148,156 @@ public class ExecuteCodeAction
 
 
 
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static ExecuteCodeInput setupExecuteCodeInput(AbstractRunScriptInput<?> input, ScriptRevision scriptRevision) throws QException
+   {
+      return setupExecuteCodeInput(input, scriptRevision, null);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public static ExecuteCodeInput setupExecuteCodeInput(AbstractRunScriptInput<?> input, ScriptRevision scriptRevision, String fileName) throws QException
+   {
+      ExecuteCodeInput executeCodeInput = new ExecuteCodeInput();
+      executeCodeInput.setInput(new HashMap<>(Objects.requireNonNullElseGet(input.getInputValues(), HashMap::new)));
+      executeCodeInput.setContext(new HashMap<>());
+
+      Map<String, Serializable> context = executeCodeInput.getContext();
+      if(input.getOutputObject() != null)
+      {
+         context.put("output", input.getOutputObject());
+      }
+
+      if(input.getScriptUtils() != null)
+      {
+         context.put("scriptUtils", input.getScriptUtils());
+      }
+
+      if(CollectionUtils.nullSafeIsEmpty(scriptRevision.getFiles()))
+      {
+         QueryInput queryInput = new QueryInput();
+         queryInput.setTableName(ScriptRevisionFile.TABLE_NAME);
+         queryInput.setFilter(new QQueryFilter(new QFilterCriteria("scriptRevisionId", QCriteriaOperator.EQUALS, scriptRevision.getId())));
+         QueryOutput queryOutput = new QueryAction().execute(queryInput);
+
+         scriptRevision.setFiles(new ArrayList<>());
+         for(QRecord record : queryOutput.getRecords())
+         {
+            scriptRevision.getFiles().add(new ScriptRevisionFile(record));
+         }
+      }
+
+      List<ScriptRevisionFile> files = scriptRevision.getFiles();
+      if(files == null || files.isEmpty())
+      {
+         throw (new QException("Script Revision " + scriptRevision.getId() + " had more than 1 associated ScriptRevisionFile (and the name to use was not specified)."));
+      }
+      else
+      {
+         String contents = null;
+         if(fileName == null || files.size() == 1)
+         {
+            contents = files.get(0).getContents();
+         }
+         else
+         {
+            for(ScriptRevisionFile file : files)
+            {
+               if(file.getFileName().equals(fileName))
+               {
+                  contents = file.getContents();
+               }
+            }
+            if(contents == null)
+            {
+               throw (new QException("Could not find file named " + fileName + " for Script Revision " + scriptRevision.getId()));
+            }
+         }
+
+         executeCodeInput.setCodeReference(new QCodeReference().withInlineCode(contents).withCodeType(QCodeType.JAVA_SCRIPT)); // todo - code type as attribute of script!!
+      }
+
+      ExecuteCodeAction.addApiUtilityToContext(context, scriptRevision);
+      context.put("qqq", new QqqScriptUtils());
+      ExecuteCodeAction.setExecutionLoggerInExecuteCodeInput(input, scriptRevision, executeCodeInput);
+
+      return (executeCodeInput);
+   }
+
+
+
+   /*******************************************************************************
+    ** Try to (dynamically) load the ApiScriptUtils object from the api middleware
+    ** module -- in case the runtime doesn't have that module deployed (e.g, not in
+    ** the project pom).
+    *******************************************************************************/
+   public static void addApiUtilityToContext(Map<String, Serializable> context, ScriptRevision scriptRevision)
+   {
+      addApiUtilityToContext(context, scriptRevision.getApiName(), scriptRevision.getApiVersion());
+   }
+
+
+
+   /*******************************************************************************
+    ** Try to (dynamically) load the ApiScriptUtils object from the api middleware
+    ** module -- in case the runtime doesn't have that module deployed (e.g, not in
+    ** the project pom).
+    *******************************************************************************/
+   public static void addApiUtilityToContext(Map<String, Serializable> context, String apiName, String apiVersion)
+   {
+      if(!StringUtils.hasContent(apiName) || !StringUtils.hasContent(apiVersion))
+      {
+         return;
+      }
+
+      try
+      {
+         Class<?> apiScriptUtilsClass  = Class.forName("com.kingsrook.qqq.api.utils.ApiScriptUtils");
+         Object   apiScriptUtilsObject = apiScriptUtilsClass.getConstructor(String.class, String.class).newInstance(apiName, apiVersion);
+         context.put("api", (Serializable) apiScriptUtilsObject);
+      }
+      catch(ClassNotFoundException e)
+      {
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // this is the only exception we're kinda expecting here - so catch for it specifically, and just log.trace - others, warn //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         LOG.trace("Couldn't load ApiScriptUtils class - qqq-middleware-api not on the classpath?");
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error adding api utility to script context", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void setExecutionLoggerInExecuteCodeInput(AbstractRunScriptInput<?> input, ScriptRevision scriptRevision, ExecuteCodeInput executeCodeInput)
+   {
+      /////////////////////////////////////////////////////////////////////////////////////////////////
+      // let caller supply a logger, or by default use StoreScriptLogAndScriptLogLineExecutionLogger //
+      /////////////////////////////////////////////////////////////////////////////////////////////////
+      QCodeExecutionLoggerInterface executionLogger = Objects.requireNonNullElseGet(input.getLogger(), () -> new StoreScriptLogAndScriptLogLineExecutionLogger(scriptRevision.getScriptId(), scriptRevision.getId()));
+      executeCodeInput.setExecutionLogger(executionLogger);
+      if(executionLogger instanceof ScriptExecutionLoggerInterface scriptExecutionLoggerInterface)
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////////
+         // if logger is aware of scripts (as opposed to a generic CodeExecution logger), give it the ids. //
+         ////////////////////////////////////////////////////////////////////////////////////////////////////
+         scriptExecutionLoggerInterface.setScriptId(scriptRevision.getScriptId());
+         scriptExecutionLoggerInterface.setScriptRevisionId(scriptRevision.getId());
+      }
+   }
+
+
+
    /*******************************************************************************
     **
     *******************************************************************************/

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

@@ -41,4 +41,24 @@ public interface QCodeExecutor
     *******************************************************************************/
    Serializable execute(QCodeReference codeReference, Map<String, Serializable> inputContext, QCodeExecutionLoggerInterface executionLogger) throws QCodeException;
 
+   /*******************************************************************************
+    ** Process an object from the script's language/runtime into a (more) native java object.
+    ** e.g., a Nashorn ScriptObjectMirror will end up as a "primitive", or a List or Map of such
+    **
+    *******************************************************************************/
+   default Object convertObjectToJava(Object object) throws QCodeException
+   {
+      return (object);
+   }
+
+   /*******************************************************************************
+    ** Convert a native java object into one for the script's language/runtime.
+    ** e.g., a java Instant to a Nashorn Date
+    **
+    *******************************************************************************/
+   default Object convertJavaObject(Object object, Object requestedTypeHint) throws QCodeException
+   {
+      return (object);
+   }
+
 }

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

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

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

@@ -0,0 +1,245 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.scripts;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.actions.permissions.TablePermissionSubType;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Object made available to scripts for access to qqq api (e.g., query, insert,
+ ** etc, plus object constructors).
+ **
+ ** Before scripts knew about the API, this class made sense and was used.
+ ** But, when scripts gained knowledge of the API, then it felt like this class could
+ ** be deleted... but, what about, a QQQ deployment without the API module...
+ ** In that case, we might still want this class... think about it.
+ **
+ ** And/Or - it turns out - sometimes using QQQ directly is "better" (?) than using
+ ** an api - so - this object may be available for other use cases (e.g., getting
+ ** a record's backendDetails (e.g., for full json from a source backend api)).
+ *******************************************************************************/
+public class QqqScriptUtils implements Serializable
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QueryInput newQueryInput()
+   {
+      return (new QueryInput());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QQueryFilter newQueryFilter()
+   {
+      return (new QQueryFilter());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QFilterCriteria newFilterCriteria()
+   {
+      return (new QFilterCriteria());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QFilterOrderBy newFilterOrderBy()
+   {
+      return (new QFilterOrderBy());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public QRecord newRecord()
+   {
+      return (new QRecord());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public List<QRecord> query(String tableName, QQueryFilter filter) throws QException
+   {
+      QueryInput queryInput = new QueryInput();
+      queryInput.setTableName(tableName);
+      queryInput.setFilter(filter);
+      PermissionsHelper.checkTablePermissionThrowing(queryInput, TablePermissionSubType.READ);
+      return (new QueryAction().execute(queryInput).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public List<QRecord> query(QueryInput queryInput) throws QException
+   {
+      PermissionsHelper.checkTablePermissionThrowing(queryInput, TablePermissionSubType.READ);
+      return (new QueryAction().execute(queryInput).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void insert(String tableName, QRecord record) throws QException
+   {
+      insert(tableName, List.of(record));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void insert(String tableName, List<QRecord> recordList) throws QException
+   {
+      InsertInput insertInput = new InsertInput();
+      insertInput.setTableName(tableName);
+      insertInput.setRecords(recordList);
+      PermissionsHelper.checkTablePermissionThrowing(insertInput, TablePermissionSubType.INSERT);
+      new InsertAction().execute(insertInput);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void update(String tableName, QRecord record) throws QException
+   {
+      update(tableName, List.of(record));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void update(String tableName, List<QRecord> recordList) throws QException
+   {
+      UpdateInput updateInput = new UpdateInput();
+      updateInput.setTableName(tableName);
+      updateInput.setRecords(recordList);
+      PermissionsHelper.checkTablePermissionThrowing(updateInput, TablePermissionSubType.EDIT);
+      new UpdateAction().execute(updateInput);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void delete(String tableName, Serializable primaryKey) throws QException
+   {
+      delete(tableName, List.of(primaryKey));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void delete(String tableName, QRecord record) throws QException
+   {
+      delete(tableName, List.of(record));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void delete(String tableName, List<?> recordOrPrimaryKeyList) throws QException
+   {
+      QTableMetaData table       = QContext.getQInstance().getTable(tableName);
+      DeleteInput    deleteInput = new DeleteInput();
+      deleteInput.setTableName(tableName);
+      List<Serializable> primaryKeyList = new ArrayList<>();
+      for(Object o : recordOrPrimaryKeyList)
+      {
+         if(o instanceof QRecord qRecord)
+         {
+            primaryKeyList.add(qRecord.getValue(table.getPrimaryKeyField()));
+         }
+         else
+         {
+            primaryKeyList.add((Serializable) o);
+         }
+      }
+      deleteInput.setPrimaryKeys(primaryKeyList);
+      PermissionsHelper.checkTablePermissionThrowing(deleteInput, TablePermissionSubType.DELETE);
+      new DeleteAction().execute(deleteInput);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void delete(String tableName, QQueryFilter filter) throws QException
+   {
+      DeleteInput deleteInput = new DeleteInput();
+      deleteInput.setTableName(tableName);
+      deleteInput.setQueryFilter(filter);
+      PermissionsHelper.checkTablePermissionThrowing(deleteInput, TablePermissionSubType.DELETE);
+      new DeleteAction().execute(deleteInput);
+   }
+
+}

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

@@ -0,0 +1,159 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2023.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.scripts;
+
+
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.scripts.logging.BuildScriptLogAndScriptLogLineExecutionLogger;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptOutput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.TestScriptInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.TestScriptOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.AdHocScriptCodeReference;
+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.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.scripts.Script;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class RecordScriptTestInterface implements TestScriptActionInterface
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void setupTestScriptInput(TestScriptInput testScriptInput, ExecuteCodeInput executeCodeInput) throws QException
+   {
+
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public void execute(TestScriptInput input, TestScriptOutput output) throws QException
+   {
+      try
+      {
+         Serializable scriptId = input.getInputValues().get("scriptId");
+         QRecord      script   = new GetAction().executeForRecord(new GetInput(Script.TABLE_NAME).withPrimaryKey(scriptId));
+
+         //////////////////////////////////////////////
+         // look up the records being tested against //
+         //////////////////////////////////////////////
+         String         tableName = script.getValueString("tableName");
+         QTableMetaData table     = QContext.getQInstance().getTable(tableName);
+         if(table == null)
+         {
+            throw (new QException("Could not find table [" + tableName + "] for script"));
+         }
+
+         String recordPrimaryKeyList = ValueUtils.getValueAsString(input.getInputValues().get("recordPrimaryKeyList"));
+         if(!StringUtils.hasContent(recordPrimaryKeyList))
+         {
+            throw (new QException("Record primary key list was not given."));
+         }
+
+         QueryOutput queryOutput = new QueryAction().execute(new QueryInput(tableName)
+            .withFilter(new QQueryFilter(new QFilterCriteria(table.getPrimaryKeyField(), QCriteriaOperator.IN, recordPrimaryKeyList.split(","))))
+            .withIncludeAssociations(true));
+         if(CollectionUtils.nullSafeIsEmpty(queryOutput.getRecords()))
+         {
+            throw (new QException("No records were found by the given primary keys."));
+         }
+
+         /////////////////////////////
+         // set up & run the action //
+         /////////////////////////////
+         RunAdHocRecordScriptInput runAdHocRecordScriptInput = new RunAdHocRecordScriptInput();
+         runAdHocRecordScriptInput.setRecordList(queryOutput.getRecords());
+
+         BuildScriptLogAndScriptLogLineExecutionLogger executionLogger = new BuildScriptLogAndScriptLogLineExecutionLogger(null, null);
+         runAdHocRecordScriptInput.setLogger(executionLogger);
+
+         runAdHocRecordScriptInput.setTableName(tableName);
+         runAdHocRecordScriptInput.setCodeReference((AdHocScriptCodeReference) input.getCodeReference());
+         RunAdHocRecordScriptOutput runAdHocRecordScriptOutput = new RunAdHocRecordScriptOutput();
+         new RunAdHocRecordScriptAction().run(runAdHocRecordScriptInput, runAdHocRecordScriptOutput);
+
+         /////////////////////////////////
+         // send outputs back to caller //
+         /////////////////////////////////
+         output.setScriptLog(executionLogger.getScriptLog());
+         output.setScriptLogLines(executionLogger.getScriptLogLines());
+         if(runAdHocRecordScriptOutput.getException().isPresent())
+         {
+            output.setException(runAdHocRecordScriptOutput.getException().get());
+         }
+      }
+      catch(QException e)
+      {
+         output.setException(e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public List<QFieldMetaData> getTestInputFields()
+   {
+      return (List.of(new QFieldMetaData("recordPrimaryKeyList", QFieldType.STRING).withLabel("Record Primary Key List")));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public List<QFieldMetaData> getTestOutputFields()
+   {
+      return (Collections.emptyList());
+   }
+
+}

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

@@ -0,0 +1,220 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qqq.backend.core.actions.scripts;
+
+
+import java.io.Serializable;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.actions.ActionHelper;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeOutput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptInput;
+import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAdHocRecordScriptOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.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.metadata.code.AdHocScriptCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.scripts.Script;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptsMetaDataProvider;
+import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class RunAdHocRecordScriptAction
+{
+   private static final QLogger LOG = QLogger.getLogger(RunAdHocRecordScriptAction.class);
+
+   private Map<Integer, ScriptRevision> scriptRevisionCacheByScriptRevisionId = new HashMap<>();
+   private Map<Integer, ScriptRevision> scriptRevisionCacheByScriptId         = new HashMap<>();
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   public void run(RunAdHocRecordScriptInput input, RunAdHocRecordScriptOutput output) throws QException
+   {
+      try
+      {
+         ActionHelper.validateSession(input);
+
+         /////////////////////////
+         // figure out the code //
+         /////////////////////////
+         ScriptRevision scriptRevision = getScriptRevision(input);
+         if(scriptRevision == null)
+         {
+            throw (new QException("Script revision was not found."));
+         }
+
+         ////////////////////////////
+         // figure out the records //
+         ////////////////////////////
+         QTableMetaData table = QContext.getQInstance().getTable(input.getTableName());
+         if(CollectionUtils.nullSafeIsEmpty(input.getRecordList()))
+         {
+            QueryInput queryInput = new QueryInput();
+            queryInput.setTableName(input.getTableName());
+            queryInput.setFilter(new QQueryFilter(new QFilterCriteria(table.getPrimaryKeyField(), QCriteriaOperator.IN, input.getRecordPrimaryKeyList())));
+            queryInput.setIncludeAssociations(true);
+            QueryOutput queryOutput = new QueryAction().execute(queryInput);
+            input.setRecordList(queryOutput.getRecords());
+         }
+
+         if(CollectionUtils.nullSafeIsEmpty(input.getRecordList()))
+         {
+            ////////////////////////////////////////
+            // just return if nothing found?  idk //
+            ////////////////////////////////////////
+            LOG.info("No records supplied as input (or found via primary keys); exiting with noop");
+            return;
+         }
+
+         /////////////
+         // run it! //
+         /////////////
+         ExecuteCodeInput executeCodeInput = ExecuteCodeAction.setupExecuteCodeInput(input, scriptRevision);
+         executeCodeInput.getInput().put("records", getRecordsForScript(input, scriptRevision));
+
+         ExecuteCodeOutput executeCodeOutput = new ExecuteCodeOutput();
+         new ExecuteCodeAction().run(executeCodeInput, executeCodeOutput);
+
+         output.setOutput(executeCodeOutput.getOutput());
+         output.setLogger(executeCodeInput.getExecutionLogger());
+      }
+      catch(Exception e)
+      {
+         output.setException(Optional.of(e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static ArrayList<? extends Serializable> getRecordsForScript(RunAdHocRecordScriptInput input, ScriptRevision scriptRevision)
+   {
+      try
+      {
+         Class<?> apiScriptUtilsClass        = Class.forName("com.kingsrook.qqq.api.utils.ApiScriptUtils");
+         Method   qRecordListToApiRecordList = apiScriptUtilsClass.getMethod("qRecordListToApiRecordList", List.class, String.class, String.class, String.class);
+         Object   apiRecordList              = qRecordListToApiRecordList.invoke(null, input.getRecordList(), input.getTableName(), scriptRevision.getApiName(), scriptRevision.getApiVersion());
+
+         // noinspection unchecked
+         return (ArrayList<? extends Serializable>) apiRecordList;
+      }
+      catch(ClassNotFoundException e)
+      {
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         // this is the only exception we're kinda expecting here - so catch for it specifically, and just log.trace - others, warn //
+         /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+         LOG.trace("Couldn't load ApiScriptUtils class - qqq-middleware-api not on the classpath?");
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Error converting QRecord list to api record list", e);
+      }
+
+      return (new ArrayList<>(input.getRecordList()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private ScriptRevision getScriptRevision(RunAdHocRecordScriptInput input) throws QException
+   {
+      AdHocScriptCodeReference codeReference = input.getCodeReference();
+      if(codeReference.getScriptRevisionRecord() != null)
+      {
+         return (new ScriptRevision(codeReference.getScriptRevisionRecord()));
+      }
+
+      if(codeReference.getScriptRevisionId() != null)
+      {
+         if(!scriptRevisionCacheByScriptRevisionId.containsKey(codeReference.getScriptRevisionId()))
+         {
+            GetInput getInput = new GetInput();
+            getInput.setTableName(ScriptRevision.TABLE_NAME);
+            getInput.setPrimaryKey(codeReference.getScriptRevisionId());
+            GetOutput getOutput = new GetAction().execute(getInput);
+            if(getOutput.getRecord() != null)
+            {
+               scriptRevisionCacheByScriptRevisionId.put(codeReference.getScriptRevisionId(), new ScriptRevision(getOutput.getRecord()));
+            }
+            else
+            {
+               scriptRevisionCacheByScriptRevisionId.put(codeReference.getScriptRevisionId(), null);
+            }
+         }
+
+         return (scriptRevisionCacheByScriptRevisionId.get(codeReference.getScriptRevisionId()));
+      }
+
+      if(codeReference.getScriptId() != null)
+      {
+         if(!scriptRevisionCacheByScriptId.containsKey(codeReference.getScriptId()))
+         {
+            QueryInput queryInput = new QueryInput();
+            queryInput.setTableName(ScriptRevision.TABLE_NAME);
+            queryInput.setFilter(new QQueryFilter(new QFilterCriteria("script.id", QCriteriaOperator.EQUALS, codeReference.getScriptId())));
+            queryInput.withQueryJoin(new QueryJoin(Script.TABLE_NAME).withBaseTableOrAlias(ScriptRevision.TABLE_NAME).withJoinMetaData(QContext.getQInstance().getJoin(ScriptsMetaDataProvider.CURRENT_SCRIPT_REVISION_JOIN_NAME)));
+            QueryOutput queryOutput = new QueryAction().execute(queryInput);
+
+            if(CollectionUtils.nullSafeHasContents(queryOutput.getRecords()))
+            {
+               scriptRevisionCacheByScriptId.put(codeReference.getScriptId(), new ScriptRevision(queryOutput.getRecords().get(0)));
+            }
+            else
+            {
+               scriptRevisionCacheByScriptId.put(codeReference.getScriptId(), null);
+            }
+         }
+
+         return (scriptRevisionCacheByScriptId.get(codeReference.getScriptId()));
+      }
+
+      throw (new QException("Code reference did not contain a scriptRevision, scriptRevisionId, or scriptId"));
+   }
+
+}

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

@@ -24,8 +24,8 @@ package com.kingsrook.qqq.backend.core.actions.scripts;
 
 import java.io.Serializable;
 import java.util.HashMap;
+import java.util.Map;
 import com.kingsrook.qqq.backend.core.actions.ActionHelper;
-import com.kingsrook.qqq.backend.core.actions.scripts.logging.StoreScriptLogAndScriptLogLineExecutionLogger;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.exceptions.QNotFoundException;
@@ -35,8 +35,7 @@ import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAssociatedScriptI
 import com.kingsrook.qqq.backend.core.model.actions.scripts.RunAssociatedScriptOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
-import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
-import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeType;
+import com.kingsrook.qqq.backend.core.model.metadata.code.AssociatedScriptCodeReference;
 import com.kingsrook.qqq.backend.core.model.scripts.Script;
 import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
 
@@ -46,6 +45,9 @@ import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
  *******************************************************************************/
 public class RunAssociatedScriptAction
 {
+   private Map<AssociatedScriptCodeReference, ScriptRevision> scriptRevisionCache = new HashMap<>();
+
+
 
    /*******************************************************************************
     **
@@ -54,36 +56,49 @@ public class RunAssociatedScriptAction
    {
       ActionHelper.validateSession(input);
 
-      Serializable scriptId = getScriptId(input);
-      if(scriptId == null)
+      ScriptRevision   scriptRevision   = getScriptRevision(input);
+      ExecuteCodeInput executeCodeInput = ExecuteCodeAction.setupExecuteCodeInput(input, scriptRevision);
+
+      if(input.getAssociatedScriptContextPrimerInterface() != null)
       {
-         throw (new QNotFoundException("The input record [" + input.getCodeReference().getRecordTable() + "][" + input.getCodeReference().getRecordPrimaryKey()
-            + "] does not have a script specified for [" + input.getCodeReference().getFieldName() + "]"));
+         input.getAssociatedScriptContextPrimerInterface().primeContext(executeCodeInput, scriptRevision);
       }
 
-      Script script = getScript(input, scriptId);
-      if(script.getCurrentScriptRevisionId() == null)
-      {
-         throw (new QNotFoundException("The script for record [" + input.getCodeReference().getRecordTable() + "][" + input.getCodeReference().getRecordPrimaryKey()
-            + "] (scriptId=" + scriptId + ") does not have a current version."));
-      }
-
-      ScriptRevision scriptRevision = getCurrentScriptRevision(input, script.getCurrentScriptRevisionId());
-
-      ExecuteCodeInput executeCodeInput = new ExecuteCodeInput(input.getInstance());
-      executeCodeInput.setSession(input.getSession());
-      executeCodeInput.setInput(new HashMap<>(input.getInputValues()));
-      executeCodeInput.setContext(new HashMap<>());
-      if(input.getOutputObject() != null)
-      {
-         executeCodeInput.getContext().put("output", input.getOutputObject());
-      }
-      executeCodeInput.setCodeReference(new QCodeReference().withInlineCode(scriptRevision.getContents()).withCodeType(QCodeType.JAVA_SCRIPT)); // todo - code type as attribute of script!!
-      executeCodeInput.setExecutionLogger(new StoreScriptLogAndScriptLogLineExecutionLogger(scriptRevision.getScriptId(), scriptRevision.getId()));
       ExecuteCodeOutput executeCodeOutput = new ExecuteCodeOutput();
       new ExecuteCodeAction().run(executeCodeInput, executeCodeOutput);
 
       output.setOutput(executeCodeOutput.getOutput());
+      output.setScriptRevisionId(scriptRevision.getId());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private ScriptRevision getScriptRevision(RunAssociatedScriptInput input) throws QException
+   {
+      if(!scriptRevisionCache.containsKey(input.getCodeReference()))
+      {
+         Serializable scriptId = getScriptId(input);
+         if(scriptId == null)
+         {
+            throw (new QNotFoundException("The input record [" + input.getCodeReference().getRecordTable() + "][" + input.getCodeReference().getRecordPrimaryKey()
+               + "] does not have a script specified for [" + input.getCodeReference().getFieldName() + "]"));
+         }
+
+         Script script = getScript(input, scriptId);
+         if(script.getCurrentScriptRevisionId() == null)
+         {
+            throw (new QNotFoundException("The script for record [" + input.getCodeReference().getRecordTable() + "][" + input.getCodeReference().getRecordPrimaryKey()
+               + "] (scriptId=" + scriptId + ") does not have a current version."));
+         }
+
+         ScriptRevision scriptRevision = getCurrentScriptRevision(input, script.getCurrentScriptRevisionId());
+         scriptRevisionCache.put(input.getCodeReference(), scriptRevision);
+      }
+
+      return scriptRevisionCache.get(input.getCodeReference());
    }
 
 
@@ -93,10 +108,10 @@ public class RunAssociatedScriptAction
     *******************************************************************************/
    private ScriptRevision getCurrentScriptRevision(RunAssociatedScriptInput input, Serializable scriptRevisionId) throws QException
    {
-      GetInput getInput = new GetInput(input.getInstance());
-      getInput.setSession(input.getSession());
+      GetInput getInput = new GetInput();
       getInput.setTableName("scriptRevision");
       getInput.setPrimaryKey(scriptRevisionId);
+      getInput.setIncludeAssociations(true);
       GetOutput getOutput = new GetAction().execute(getInput);
       if(getOutput.getRecord() == null)
       {
@@ -114,8 +129,7 @@ public class RunAssociatedScriptAction
     *******************************************************************************/
    private Script getScript(RunAssociatedScriptInput input, Serializable scriptId) throws QException
    {
-      GetInput getInput = new GetInput(input.getInstance());
-      getInput.setSession(input.getSession());
+      GetInput getInput = new GetInput();
       getInput.setTableName("script");
       getInput.setPrimaryKey(scriptId);
       GetOutput getOutput = new GetAction().execute(getInput);
@@ -136,8 +150,7 @@ public class RunAssociatedScriptAction
     *******************************************************************************/
    private Serializable getScriptId(RunAssociatedScriptInput input) throws QException
    {
-      GetInput getInput = new GetInput(input.getInstance());
-      getInput.setSession(input.getSession());
+      GetInput getInput = new GetInput();
       getInput.setTableName(input.getCodeReference().getRecordTable());
       getInput.setPrimaryKey(input.getCodeReference().getRecordPrimaryKey());
       GetOutput getOutput = new GetAction().execute(getInput);

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

@@ -31,6 +31,8 @@ import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.StoreAssociatedScriptInput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.StoreAssociatedScriptOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
@@ -47,6 +49,7 @@ 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.tables.AssociatedScript;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.scripts.StoreScriptRevisionProcessStep;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
 
@@ -83,8 +86,7 @@ public class StoreAssociatedScriptAction
       /////////////////////////////////////////////////////////////
       QRecord associatedRecord;
       {
-         GetInput getInput = new GetInput(input.getInstance());
-         getInput.setSession(input.getSession());
+         GetInput getInput = new GetInput();
          getInput.setTableName(input.getTableName());
          getInput.setPrimaryKey(input.getRecordPrimaryKey());
          getInput.setShouldGenerateDisplayValues(true);
@@ -107,8 +109,7 @@ public class StoreAssociatedScriptAction
          ////////////////////////////////////////////////////////////////////
          // get the script type - that'll be part of the new script's name //
          ////////////////////////////////////////////////////////////////////
-         GetInput getInput = new GetInput(input.getInstance());
-         getInput.setSession(input.getSession());
+         GetInput getInput = new GetInput();
          getInput.setTableName("scriptType");
          getInput.setPrimaryKey(associatedScript.getScriptTypeId());
          getInput.setShouldGenerateDisplayValues(true);
@@ -125,8 +126,7 @@ public class StoreAssociatedScriptAction
          script = new QRecord();
          script.setValue("scriptTypeId", associatedScript.getScriptTypeId());
          script.setValue("name", associatedRecord.getRecordLabel() + " - " + scriptType.getRecordLabel());
-         InsertInput insertInput = new InsertInput(input.getInstance());
-         insertInput.setSession(input.getSession());
+         InsertInput insertInput = new InsertInput();
          insertInput.setTableName("script");
          insertInput.setRecords(List.of(script));
          InsertOutput insertOutput = new InsertAction().execute(insertInput);
@@ -135,8 +135,7 @@ public class StoreAssociatedScriptAction
          /////////////////////////////////////////////////////////////
          // update the associated record to point at the new script //
          /////////////////////////////////////////////////////////////
-         UpdateInput updateInput = new UpdateInput(input.getInstance());
-         updateInput.setSession(input.getSession());
+         UpdateInput updateInput = new UpdateInput();
          updateInput.setTableName(input.getTableName());
          updateInput.setRecords(List.of(new QRecord()
             .withValue(table.getPrimaryKeyField(), associatedRecord.getValue(table.getPrimaryKeyField()))
@@ -149,21 +148,18 @@ public class StoreAssociatedScriptAction
          ////////////////////////////////////////
          // get the existing script, to update //
          ////////////////////////////////////////
-         GetInput getInput = new GetInput(input.getInstance());
-         getInput.setSession(input.getSession());
+         GetInput getInput = new GetInput();
          getInput.setTableName("script");
          getInput.setPrimaryKey(existingScriptId);
          GetOutput getOutput = new GetAction().execute(getInput);
          script = getOutput.getRecord();
 
-         QueryInput queryInput = new QueryInput(input.getInstance());
-         queryInput.setSession(input.getSession());
+         QueryInput queryInput = new QueryInput();
          queryInput.setTableName("scriptRevision");
          queryInput.setFilter(new QQueryFilter()
             .withCriteria(new QFilterCriteria("scriptId", QCriteriaOperator.EQUALS, List.of(script.getValue("id"))))
             .withOrderBy(new QFilterOrderBy("sequenceNo", false))
-         );
-         queryInput.setLimit(1);
+            .withLimit(1));
          QueryOutput queryOutput = new QueryAction().execute(queryInput);
          if(!queryOutput.getRecords().isEmpty())
          {
@@ -187,41 +183,19 @@ public class StoreAssociatedScriptAction
          }
       }
 
-      QRecord scriptRevision = new QRecord()
-         .withValue("scriptId", script.getValue("id"))
-         .withValue("contents", input.getCode())
-         .withValue("commitMessage", commitMessage)
-         .withValue("sequenceNo", nextSequenceNo);
-
-      try
-      {
-         scriptRevision.setValue("author", input.getSession().getUser().getFullName());
-      }
-      catch(Exception e)
-      {
-         scriptRevision.setValue("author", "Unknown");
-      }
-
-      InsertInput insertInput = new InsertInput(input.getInstance());
-      insertInput.setSession(input.getSession());
-      insertInput.setTableName("scriptRevision");
-      insertInput.setRecords(List.of(scriptRevision));
-      InsertOutput insertOutput = new InsertAction().execute(insertInput);
-      scriptRevision = insertOutput.getRecords().get(0);
-
-      ////////////////////////////////////////////////////
-      // update the script to point at the new revision //
-      ////////////////////////////////////////////////////
-      script.setValue("currentScriptRevisionId", scriptRevision.getValue("id"));
-      UpdateInput updateInput = new UpdateInput(input.getInstance());
-      updateInput.setSession(input.getSession());
-      updateInput.setTableName("script");
-      updateInput.setRecords(List.of(script));
-      new UpdateAction().execute(updateInput);
+      RunBackendStepInput storeScriptRevisionInput = new RunBackendStepInput();
+      storeScriptRevisionInput.addValue("scriptId", script.getValue("id"));
+      storeScriptRevisionInput.addValue("commitMessage", commitMessage);
+      storeScriptRevisionInput.addValue("apiName", input.getApiName());
+      storeScriptRevisionInput.addValue("apiVersion", input.getApiVersion());
+      storeScriptRevisionInput.addValue("fileNames", "script");
+      storeScriptRevisionInput.addValue("fileContents:script", input.getCode());
+      RunBackendStepOutput storeScriptRevisionOutput = new RunBackendStepOutput();
+      new StoreScriptRevisionProcessStep().run(storeScriptRevisionInput, storeScriptRevisionOutput);
 
       output.setScriptId(script.getValueInteger("id"));
       output.setScriptName(script.getValueString("name"));
-      output.setScriptRevisionId(scriptRevision.getValueInteger("id"));
-      output.setScriptRevisionSequenceNo(scriptRevision.getValueInteger("sequenceNo"));
+      output.setScriptRevisionId(storeScriptRevisionOutput.getValueInteger("scriptRevisionId"));
+      output.setScriptRevisionSequenceNo(storeScriptRevisionOutput.getValueInteger("scriptRevisionSequenceNo"));
    }
 }

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

@@ -32,6 +32,7 @@ import com.kingsrook.qqq.backend.core.model.actions.scripts.ExecuteCodeOutput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.TestScriptInput;
 import com.kingsrook.qqq.backend.core.model.actions.scripts.TestScriptOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.scripts.ScriptRevision;
 
 
 /*******************************************************************************
@@ -47,7 +48,7 @@ public interface TestScriptActionInterface
     ** Note - such a method may want or need to put an "output" object into the
     ** executeCodeInput's context map.
     *******************************************************************************/
-   void setupTestScriptInput(TestScriptInput testScriptInput, ExecuteCodeInput executeCodeInput);
+   void setupTestScriptInput(TestScriptInput testScriptInput, ExecuteCodeInput executeCodeInput) throws QException;
 
 
    /*******************************************************************************
@@ -80,20 +81,31 @@ public interface TestScriptActionInterface
     *******************************************************************************/
    default void execute(TestScriptInput input, TestScriptOutput output) throws QException
    {
-      ExecuteCodeInput executeCodeInput = new ExecuteCodeInput(input.getInstance());
-      executeCodeInput.setSession(input.getSession());
+      /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      // todo - could this be merged with the various other script runners, to use ExecuteCodeAction.setupExecuteCodeInput?? //
+      /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+      ExecuteCodeInput executeCodeInput = new ExecuteCodeInput();
       executeCodeInput.setContext(new HashMap<>());
 
       executeCodeInput.setCodeReference(input.getCodeReference());
       BuildScriptLogAndScriptLogLineExecutionLogger executionLogger = new BuildScriptLogAndScriptLogLineExecutionLogger(null, null);
       executeCodeInput.setExecutionLogger(executionLogger);
 
-      setupTestScriptInput(input, executeCodeInput);
-
-      ExecuteCodeOutput executeCodeOutput = new ExecuteCodeOutput();
-
       try
       {
+         setupTestScriptInput(input, executeCodeInput);
+
+         ScriptRevision scriptRevision = new ScriptRevision().withApiName(input.getApiName()).withApiVersion(input.getApiVersion());
+
+         if(this instanceof AssociatedScriptContextPrimerInterface associatedScriptContextPrimerInterface)
+         {
+            associatedScriptContextPrimerInterface.primeContext(executeCodeInput, scriptRevision);
+         }
+
+         ExecuteCodeOutput executeCodeOutput = new ExecuteCodeOutput();
+
+         ExecuteCodeAction.addApiUtilityToContext(executeCodeInput.getContext(), scriptRevision);
+
          new ExecuteCodeAction().run(executeCodeInput, executeCodeOutput);
          output.setOutputObject(processTestScriptOutput(executeCodeOutput));
       }