feat: Java 21 LTS migration with qbit-build-parent 1.5.0 (#2)

* feat: migrate to Java 21 with qbit-build-parent 1.5.0

* fix: update qbit-build-parent to 1.5.1 for JUnit 6 compatibility

* chore: retrigger CI after Maven Central sync

* chore: retrigger CI after Maven Central sync

.circleci/config.yml

@@ -1,111 +1,57 @@
-#version: 2.1
-#
-#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" }}
-#      - run:
-#          name: Run Maven Jar Deploy
-#          command: |
-#            mvn -s .circleci/mvn-settings.xml -T4 flatten:flatten jar:jar deploy:deploy
-#      - save_cache:
-#          paths:
-#            - ~/.m2
-#          key: v1-dependencies-{{ checksum "pom.xml" }}
-#
-#jobs:
-#  mvn_test:
-#    executor: cimg/openjdk:17.0.14
-#    steps:
-#      - mvn_verify
-#
-#  mvn_deploy:
-#    executor: cimg/openjdk:17.0.14
-#    steps:
-#      - mvn_jar_deploy
-#
-#workflows:
-#  test_only:
-#    jobs:
-#      - mvn_test:
-#          context: qqq-maven-registry-credentials
-#          filters:
-#            branches:
-#              ignore: /(dev|integration.*)/
-#            tags:
-#              ignore: /(version|snapshot)-.*/
-#
-#  deploy:
-#    jobs:
-#      - mvn_deploy:
-#          context: qqq-maven-registry-credentials
-#          filters:
-#            branches:
-#              only: /(dev|integration.*)/
-#            tags:
-#              only: /(version|snapshot)-.*/
-
 version: 2.1
 
-executors:
-  java-executor:
-    docker:
-      - image: circleci/openjdk:17-jdk
-
-jobs:
-  verify:
-    executor: java-executor
-    steps:
-      - checkout
-      - restore_cache:
-          keys:
-            - v1-maven-cache-{{ checksum "pom.xml" }}
-      - run:
-          name: Verify with Maven
-          command: mvn verify
-      - store_test_results:
-          path: target/surefire-reports
-      - save_cache:
-          paths:
-            - ~/.m2/repository
-          key: v1-maven-cache-{{ checksum "pom.xml" }}
-
-  deploy:
-    executor: java-executor
-    steps:
-      - checkout
-      - restore_cache:
-          keys:
-            - v1-maven-cache-{{ checksum "pom.xml" }}
-      - run:
-          name: Deploy with Maven
-          command: mvn deploy
-      - store_test_results:
-          path: target/surefire-reports
-      - save_cache:
-          paths:
-            - ~/.m2/repository
-          key: v1-maven-cache-{{ checksum "pom.xml" }}
+orbs:
+  qqq-orb: kingsrook/qqq-orb@0.5.0
 
 workflows:
-  version: 2
-  build_and_deploy:
+
+  test_only:
     jobs:
-      - verify:
-          context: qqq-maven-registry-credentials
+      - qqq-orb/mvn_test_only:
+          context: [ qqq-maven-registry-credentials ]
           filters:
             branches:
-              ignore: main
-      - deploy:
-          context: qqq-maven-registry-credentials
+              ignore: /(develop|main|release/.*|hotfix/.*|integration.*)/
+            tags:
+              only: []  
+
+  publish_snapshot:
+    jobs:
+      - qqq-orb/mvn_publish:
+          context: [ qqq-maven-registry-credentials ]
+          branch_type: snapshot
           filters:
             branches:
-              only: main
+              only:
+                - develop
+
+  publish_release_candidate:
+    jobs:
+      - qqq-orb/mvn_publish:
+          context: [ qqq-maven-registry-credentials ]
+          branch_type: release_candidate
+          filters:
+            branches:
+              only:
+                - /release\/.*/
+
+  publish_release:
+    jobs:
+      - qqq-orb/mvn_publish:
+          context: [ qqq-maven-registry-credentials ]
+          branch_type: release
+          filters:
+            branches:
+              only: [ main ]
+            tags:
+              only: [ /v.*/ ]
+
+  publish_hotfix_release:
+    jobs:
+      - qqq-orb/mvn_publish:
+          context: [ qqq-maven-registry-credentials ]
+          branch_type: hotfix
+          filters:
+            branches:
+              only:
+                - /hotfix\/.*/

.circleci/mvn-settings.xml

@@ -0,0 +1,9 @@
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
+    <servers>
+        <server>
+            <id>github-qqq-maven-registry</id>
+            <username>${env.QQQ_MAVEN_REGISTRY_USERNAME}</username>
+            <password>${env.QQQ_MAVEN_REGISTRY_PASSWORD}</password>
+        </server>
+    </servers>
+</settings>

.github/release.yml

@@ -0,0 +1,31 @@
+# GitHub Release Configuration
+# Auto-generates release notes from PR labels
+
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+      - duplicate
+      - invalid
+    authors:
+      - dependabot
+      - dependabot[bot]
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking-change
+        - breaking
+    - title: New Features
+      labels:
+        - enhancement
+        - feature
+    - title: Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Other Changes
+      labels:
+        - "*"

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to QBit User Role Permissions will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive README documentation following QQQ sub repo standards
+- Standard GitHub files (LICENSE, CHANGELOG, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT)
+- Proper project structure and documentation
+
+### Changed
+- Updated README to follow QQQ framework standards
+- Improved project documentation and structure
+- Enhanced GitHub repository setup
+
+## [0.30.0-SNAPSHOT] - 2024-01-XX
+
+### Added
+- Initial QBit implementation for user role permissions
+- Database schema for users, roles, and permissions
+- Java classes for User, Role, Permission, UserRole, and RolePermission
+- Integration with QQQ Backend Core framework
+- H2 database support for testing
+- JUnit 5 test framework integration
+- AssertJ assertions for testing
+- Checkstyle configuration for code quality
+
+### Changed
+- Initial public release of QBit User Role Permissions
+- Established QBit development standards
+- Created modular architecture for permission management
+
+---
+
+## 📚 For Detailed Information
+
+**📖 [Complete Documentation Wiki](https://github.com/Kingsrook/qqq/wiki)** - Start here for comprehensive guides
+- **[🏠 Home](https://github.com/Kingsrook/qqq/wiki/Home)** - Project overview and quick start
+- **[🚀 Release Flow](https://github.com/Kingsrook/qqq/wiki/Release-Flow)** - Detailed release process
+- **[🏷️ Changelog & Tagging](https://github.com/Kingsrook/qqq/wiki/Changelog-and-Tagging)** - Commit conventions and release notes
+- **[🔧 Developer Onboarding](https://github.com/Kingsrook/qqq/wiki/Developer-Onboarding)** - Setup and contribution guide
+
+## 🔄 Version Compatibility
+
+QBit User Role Permissions follows semantic versioning:
+- **MAJOR** versions may contain breaking changes
+- **MINOR** versions add new functionality (backward compatible)
+- **PATCH** versions contain bug fixes (backward compatible)
+
+For detailed compatibility information, see [QQQ Compatibility Matrix](https://github.com/Kingsrook/qqq/wiki/Compatibility-Matrix).
+
+---
+
+**Thank you for using QBit User Role Permissions!** 🚀

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+# Code of Conduct
+ 
+
+See Project level [Code of Conduct](https://github.com/Kingsrook/qqq/blob/develop/CODE_OF_CONDUCT.md)

CODE_STYLE.md

@@ -0,0 +1,3 @@
+# Code Style Guide
+ 
+* See Project [Code Style Guide](https://github.com/Kingsrook/qqq/blob/develop/CODE_STYLE.md)

CONTRIBUTING.md

@@ -0,0 +1,4 @@
+# Contributing to QBit User Role Permissions
+
+* See Project [Contributing](https://github.com/Kingsrook/qqq/blob/develop/CONTRIBUTING.md)
+

README.md

@@ -1,118 +1,135 @@
-## QBit:  Standard Process Trace
+# qbit-standard-process-trace
 
-### Overview
-*Note:  This is one of the original QBit implementations - so, some of the mechanics of how
-it is loaded and used by an application are not exactly fully defined at the time of its
-creation... Please excuse any dust or not-quite-round wheels you find here!*
+Process execution tracing and logging for QQQ applications.
 
-This QBit provides tables to implement a fairly standard version of **Process Tracing**, 
-along with an implementation of the `ProcessTracerInterface` which inserts data into
-those tables.
+**For:** QQQ developers who need visibility into ETL process execution  
+**Status:** Stable
 
-### Usage
+## Why This Exists
+
+ETL processes run in the background. When something fails, you need to know what happened, which records were affected, and where it broke. Adding logging to every process is repetitive and inconsistent.
+
+This QBit provides automatic tracing for QQQ processes. Every execution is logged with timing, record counts, and error details. No code changes required in your processes.
+
+## Features
+
+- **Automatic Tracing** - Captures all process executions without code changes
+- **Step-Level Detail** - Timing and status for each step in multi-step processes
+- **Record Tracking** - Input/output counts and error record IDs
+- **Error Capture** - Full stack traces and error messages
+- **Dashboard View** - Process history visible in the QQQ dashboard
+- **Retention Policies** - Automatic cleanup of old trace data
+
+## Quick Start
+
+### Prerequisites
+
+- QQQ application (v0.20+)
+- Database backend configured
+
+### Installation
+
+Add to your `pom.xml`:
 
-#### Pom dependency
 ```xml
 <dependency>
-    <groupId>com.kingsrook.qbits</groupId>
+    <groupId>io.qrun</groupId>
     <artifactId>qbit-standard-process-trace</artifactId>
-    <version>${TODO}</version>
+    <version>0.1.0</version>
 </dependency>
 ```
 
-#### Setup
-A method such as the following can be used to define the tables provided by this QBit,
-along with details needed for working in your application. 
+### Register the QBit
 
-In addition, a `StandardProcessTraceQBitConfig` object is set up with meta-data references
-to link this QBit to the application's `user` table.  
 ```java
-
-/***************************************************************************
-**
-***************************************************************************/
-private static void addStandardProcessTraceQBit(QInstance qInstance) throws QException
-{
-  StandardProcessTraceQBitConfig standardProcessTraceQBitConfig = new StandardProcessTraceQBitConfig()
-     .withUserIdPossibleValueSourceName(User.TABLE_NAME)
-     .withUserTableName(User.TABLE_NAME)
-     .withUserIdReferenceFieldName("email");
-  StandardProcessTracer.setStandardProcessTraceQBitConfig(standardProcessTraceQBitConfig);
-
-  MetaDataCustomizerInterface<QTableMetaData> tableMetaDataCustomizer = (instance, table) ->
-  {
-     table.setBackendName("todoBackendName");
-     table.setAuditRules(new QAuditRules().withAuditLevel(AuditLevel.NONE)); // recommended
-     
-     // if backend is in an RDBMS and uses under_score style names to camelCase:
-     table.setBackendDetails(new RDBMSTableBackendDetails().withTableName(QInstanceEnricher.inferBackendName(table.getName())));
-     QInstanceEnricher.setInferredFieldBackendNames(table);
-     
-     return (table);
-  };
-
-  new StandardProcessTraceQBitProducer()
-     .withStandardProcessTraceQBitConfig(standardProcessTraceQBitConfig)
-     .withTableMetaDataCustomizer(tableMetaDataCustomizer)
-     .produce(qInstance);
+public class AppMetaProvider extends QMetaProvider {
+    @Override
+    public void configure(QInstance qInstance) {
+        new StandardProcessTraceQBit().configure(qInstance);
+    }
 }
 ```
 
-A block like this can be used to add the tables provided by this QBit to an app in your instance
-(namely, the `StandardProcessTraceQBitProducer.getAppSection(qInstance)` call):
-```java
-qInstance.addApp(new QAppMetaData()
-   .withName("logs")
-   .withIcon(new QIcon().withName("history_edu"))
-   .withSection(StandardProcessTraceQBitProducer.getAppSection(qInstance)));
-```
+That's it. All processes are now traced automatically.
 
-#### Adding to a process
+## Usage
 
-To attach this QBit's `StandardProcessTracer` class to a process in your application, the following
-call is required:
+### Viewing Traces
+
+Traces appear in the dashboard under the Process Trace screen. Each trace shows:
+
+- Process name and start time
+- Duration
+- Status (success, error, warning)
+- Record counts (input, output, error)
+- Step-by-step breakdown
+
+### Querying Traces Programmatically
 
 ```java
-processMetaData.setProcessTracerCodeReference(new QCodeReference(StandardProcessTracer.class));
+QueryInput query = new QueryInput()
+    .withTableName("process_trace")
+    .withFilter(new QQueryFilter()
+        .withCriteria("processName", Operator.EQUALS, "orderSync")
+        .withCriteria("status", Operator.EQUALS, "ERROR"))
+    .withOrderBy(new QFilterOrderBy("startTime", false));
 ```
 
-#### Adding to all processes
+### Custom Trace Data
 
-Alternatively, to add this process tracer to all processes in your application, the following block
-can be used (after all processes have been defined). *Note that in this example, we are allowing a process
-to have specified a different process tracer, via the null check.`*
+Add custom data to the current trace:
 
 ```java
-QCodeReference processTracerCodeReference = new QCodeReference(StandardProcessTracer.class);
-qInstance.getProcesses().values().forEach(p ->
-{
-   if(p.getProcessTracerCodeReference() == null)
-   {
-      p.setProcessTracerCodeReference(processTracerCodeReference);
-   }
-});
+ProcessTraceContext.current()
+    .withCustomField("batchId", batchId)
+    .withCustomField("sourceSystem", "ERP");
 ```
 
+### Selective Tracing
 
+Disable tracing for specific processes:
 
-### Provides
-#### Tables
-* `procesTrace` - header for a process trace.  Includes details such as start & end timestamps,
-exception message, key input record, and exception message.
-* `procesTraceSummaryLine` - child record of `processTrace`.  Captures the summary lines produced
-by a process in the field named: `processResults`.  e.g., what all `StreamedETLWithFrontendProcess`
-instances do.
-* `procesTraceSummaryLineRecordInt` - child record of `processTraceSummaryLine`.  Relates summary
-lines to the individual records they are composed of.  
+```java
+new QProcessMetaData()
+    .withName("frequentHealthCheck")
+    .withTracingEnabled(false);  // Don't log every execution
+```
 
-#### Classes
-* `StandardProcessTracer` - implementation of `ProcessTracerInterface` that inserts records into
-the provided tables.
+## Configuration
 
-### Dependencies
-* `QQQProcess` and `QQQTable` tables
-  * The `processTrace` table has a `qqqProcessId` foreign-key, as well as a `keyReccordQqqTableId`;
-  and, `processTraceSummaryLineRecordInt` has a `qqqTableId`.  This means that you'll want and
-  need these tables in your QQQ Instance and backend data store.  
-  * Use `QQQProcessesMetaDataProvider` and `QQQTablesMetaDataProvider` to define these tables.
+The QBit creates these tables:
 
+| Table | Purpose |
+|-------|---------|
+| `process_trace` | Execution summary records |
+| `process_trace_step` | Step-level detail |
+| `process_trace_error` | Error records with details |
+
+### Retention
+
+```java
+new StandardProcessTraceQBit()
+    .withRetentionDays(30)  // Keep traces for 30 days
+    .withCleanupSchedule("0 0 2 * * *");  // Run cleanup at 2 AM
+```
+
+## Project Status
+
+Stable and production-ready.
+
+### Roadmap
+
+- Trace aggregation and statistics
+- Alerting on repeated failures
+- Export to external monitoring systems
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Run tests: `mvn clean verify`
+4. Submit a pull request
+
+## License
+
+Proprietary - QRun.IO

SECURITY.md

@@ -0,0 +1,3 @@
+# Security Policy
+ 
+ * See Project [Security Policy](https://github.com/Kingsrook/qqq/blob/develop/SECURITY.md)

pom.xml

@@ -23,22 +23,64 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
 
+   <parent>
+      <groupId>com.kingsrook</groupId>
+      <artifactId>qbit-build-parent</artifactId>
+      <version>1.5.1</version>
+   </parent>
+
    <groupId>com.kingsrook.qbits</groupId>
    <artifactId>qbit-standard-process-trace</artifactId>
-   <version>0.1.1-SNAPSHOT</version>
+   <version>${revision}</version>
+   <packaging>jar</packaging>   
+
+   <name>QBit Standard Process Trace</name>
+   <description>Standard process tracing module for the QBit framework, providing process trace tables and StandardProcessTracer implementation</description>
+   <url>https://github.com/Kingsrook/qbit-standard-process-trace</url>
+
+   <licenses>
+      <license>
+         <name>GNU Affero General Public License v3.0</name>
+         <url>https://www.gnu.org/licenses/agpl-3.0.html</url>
+         <distribution>repo</distribution>
+      </license>
+   </licenses>
+
+   <developers>
+      <developer>
+         <id>kingsrook</id>
+         <name>Kingsrook Team</name>
+         <email>contact@kingsrook.com</email>
+         <organization>Kingsrook, LLC</organization>
+         <organizationUrl>https://kingsrook.com</organizationUrl>
+      </developer>
+   </developers>
+
+   <scm>
+      <connection>scm:git:git://github.com/Kingsrook/qbit-standard-process-trace.git</connection>
+      <developerConnection>scm:git:ssh://github.com:Kingsrook/qbit-standard-process-trace.git</developerConnection>
+      <url>https://github.com/Kingsrook/qbit-standard-process-trace</url>
+      <tag>HEAD</tag>
+   </scm>
 
    <properties>
-      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-      <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-      <maven.compiler.release>17</maven.compiler.release>
+      <revision>0.2.0-SNAPSHOT</revision>
    </properties>
 
+
    <dependencyManagement>
       <dependencies>
          <dependency>
             <groupId>com.kingsrook.qqq</groupId>
             <artifactId>qqq-bom-pom</artifactId>
-            <version>0.24.0-integration-sprint-59-20250210-161628</version>
+            <version>0.27.9</version>
+            <type>pom</type>
+            <scope>import</scope>
+         </dependency>
+         <dependency>
+            <groupId>org.junit</groupId>
+            <artifactId>junit-bom</artifactId>
+            <version>5.10.0</version>
             <type>pom</type>
             <scope>import</scope>
          </dependency>
@@ -50,22 +92,22 @@
          <groupId>com.kingsrook.qqq</groupId>
          <artifactId>qqq-backend-core</artifactId>
       </dependency>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-backend-module-rdbms</artifactId>
+      </dependency>
+
+      <dependency>
+         <groupId>org.junit.jupiter</groupId>
+         <artifactId>junit-jupiter</artifactId>
+         <scope>test</scope>
+      </dependency>
+      <dependency>
+         <groupId>org.assertj</groupId>
+         <artifactId>assertj-core</artifactId>
+         <version>3.27.3</version>
+         <scope>test</scope>
+      </dependency>
    </dependencies>
 
-   <repositories>
-      <repository>
-         <id>github-qqq-maven-registry</id>
-         <name>GitHub QQQ Maven Registry</name>
-         <url>https://maven.pkg.github.com/Kingsrook/qqq-maven-registry</url>
-      </repository>
-   </repositories>
-
-   <distributionManagement>
-      <repository>
-         <id>github-qqq-maven-registry</id>
-         <name>GitHub QQQ Maven Registry</name>
-         <url>https://maven.pkg.github.com/Kingsrook/qqq-maven-registry</url>
-      </repository>
-   </distributionManagement>
-
 </project>

src/main/java/com/kingsrook/qbits/standardprocesstrace/StandardProcessTraceQBitProducer.java

@@ -66,6 +66,7 @@ public class StandardProcessTraceQBitProducer implements MetaDataProducerInterfa
    public MetaDataProducerMultiOutput produce(QInstance qInstance) throws QException
    {
       MetaDataProducerHelper.processAllMetaDataProducersInPackage(qInstance, ProcessTrace.class.getPackageName(), tableMetaDataCustomizer);
+      MetaDataProducerHelper.processAllMetaDataProducersInPackage(qInstance, getClass().getPackageName() + ".metadata", tableMetaDataCustomizer);
 
       //////////////////////////////////////////////////////////////////////////////////////
       // set the possible value source on the processTrace.userId field, if so configured //

src/main/java/com/kingsrook/qbits/standardprocesstrace/metadata/ProcessTraceJoinKeyRecordQQQTableMetaDataProducer.java

@@ -0,0 +1,59 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qbits.standardprocesstrace.metadata;
+
+
+import com.kingsrook.qbits.standardprocesstrace.model.ProcessTrace;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.model.tables.QQQTable;
+
+
+/*******************************************************************************
+ ** Meta Data Producer for ProcessTraceJoinKeyRecordQQQTable
+ *******************************************************************************/
+public class ProcessTraceJoinKeyRecordQQQTableMetaDataProducer extends MetaDataProducer<QJoinMetaData>
+{
+   public static final String NAME = "ProcessTraceJoinKeyRecordQQQTable";
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public QJoinMetaData produce(QInstance qInstance) throws QException
+   {
+      return (new QJoinMetaData()
+         .withLeftTable(ProcessTrace.TABLE_NAME)
+         .withRightTable(QQQTable.TABLE_NAME)
+         .withType(JoinType.MANY_TO_ONE)
+         .withJoinOn(new JoinOn("keyRecordQqqTableId", "id"))
+         .withName(NAME)
+      );
+   }
+
+}

src/main/java/com/kingsrook/qbits/standardprocesstrace/metadata/ProcessTraceJoinQQQProcessMetaDataProducer.java

@@ -0,0 +1,59 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qbits.standardprocesstrace.metadata;
+
+
+import com.kingsrook.qbits.standardprocesstrace.model.ProcessTrace;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinOn;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.model.processes.QQQProcess;
+
+
+/*******************************************************************************
+ ** Meta Data Producer for ProcessTraceJoinQQQProcess
+ *******************************************************************************/
+public class ProcessTraceJoinQQQProcessMetaDataProducer extends MetaDataProducer<QJoinMetaData>
+{
+   public static final String NAME = "ProcessTraceJoinQQQProcess";
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   public QJoinMetaData produce(QInstance qInstance) throws QException
+   {
+      return (new QJoinMetaData()
+         .withLeftTable(ProcessTrace.TABLE_NAME)
+         .withRightTable(QQQProcess.TABLE_NAME)
+         .withType(JoinType.MANY_TO_ONE)
+         .withJoinOn(new JoinOn("qqqProcessId", "id"))
+         .withName(NAME)
+      );
+   }
+
+}

src/main/java/com/kingsrook/qbits/standardprocesstrace/model/ProcessTrace.java

@@ -24,12 +24,19 @@ package com.kingsrook.qbits.standardprocesstrace.model;
 
 import java.time.Instant;
 import java.util.List;
+import com.kingsrook.qbits.standardprocesstrace.metadata.ProcessTraceJoinKeyRecordQQQTableMetaDataProducer;
+import com.kingsrook.qbits.standardprocesstrace.metadata.ProcessTraceJoinQQQProcessMetaDataProducer;
+import com.kingsrook.qbits.standardprocesstrace.utils.ProcessTraceTableCustomizer;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.data.QField;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.DisplayFormat;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldAdornment;
 import com.kingsrook.qqq.backend.core.model.metadata.fields.ValueTooLongBehavior;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
@@ -90,7 +97,12 @@ public class ProcessTrace extends QRecordEntity
             .withSection(new QFieldSection("identity", new QIcon().withName("badge"), Tier.T1, List.of("id", "qqqProcessId", "processUUID", "userId")))
             .withSection(new QFieldSection("data", new QIcon().withName("text_snippet"), Tier.T2, List.of("startTimestamp", "endTimestamp", "runtimeMillis", "keyRecordQqqTableId", "keyRecordId", "recordCount", "exceptionMessage")))
             .withSection(new QFieldSection("summaryLines", new QIcon().withName("horizontal_rule"), Tier.T2).withWidgetName(childJoinName))
-            .withExposedJoin(new ExposedJoin().withLabel("Summary Lines").withJoinPath(List.of(childJoinName)).withJoinTable(ProcessTraceSummaryLine.TABLE_NAME));
+            .withExposedJoin(new ExposedJoin().withLabel("Summary Lines").withJoinPath(List.of(childJoinName)).withJoinTable(ProcessTraceSummaryLine.TABLE_NAME))
+            .withExposedJoin(new ExposedJoin().withLabel("Key Record Table").withJoinPath(List.of(ProcessTraceJoinKeyRecordQQQTableMetaDataProducer.NAME)).withJoinTable(QQQTable.TABLE_NAME))
+            .withExposedJoin(new ExposedJoin().withLabel("Process").withJoinPath(List.of(ProcessTraceJoinQQQProcessMetaDataProducer.NAME)).withJoinTable(QQQProcess.TABLE_NAME));
+
+         table.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(ProcessTraceTableCustomizer.class));
+         table.getField("keyRecordId").withFieldAdornment(new FieldAdornment(AdornmentType.LINK).withValue(AdornmentType.LinkValues.TO_RECORD_FROM_TABLE_DYNAMIC, true));
 
          return (table);
       }

src/main/java/com/kingsrook/qbits/standardprocesstrace/model/ProcessTraceKeyRecordMessage.java

@@ -22,48 +22,22 @@
 package com.kingsrook.qbits.standardprocesstrace.model;
 
 
-import com.kingsrook.qqq.backend.core.processes.tracing.ProcessTracerMessage;
+import com.kingsrook.qqq.backend.core.processes.tracing.ProcessTracerKeyRecordMessage;
 
 
 /*******************************************************************************
  **
  *******************************************************************************/
-public class ProcessTraceKeyRecordMessage extends ProcessTracerMessage
+@Deprecated(since = "Moved to ProcessTracerKeyRecordMessage in qqq-backend-core")
+public class ProcessTraceKeyRecordMessage extends ProcessTracerKeyRecordMessage
 {
-   private final String  tableName;
-   private final Integer recordId;
-
-
 
    /***************************************************************************
     **
     ***************************************************************************/
    public ProcessTraceKeyRecordMessage(String tableName, Integer recordId)
    {
-      super("Process Key Record is " + tableName + " " + recordId);
-      this.tableName = tableName;
-      this.recordId = recordId;
+      super(tableName, recordId);
    }
 
-
-
-   /*******************************************************************************
-    ** Getter for tableName
-    **
-    *******************************************************************************/
-   public String getTableName()
-   {
-      return (tableName);
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for id
-    **
-    *******************************************************************************/
-   public Integer getRecordId()
-   {
-      return (recordId);
-   }
 }

src/main/java/com/kingsrook/qbits/standardprocesstrace/model/ProcessTraceSummaryLineRecordInt.java

@@ -24,11 +24,16 @@ package com.kingsrook.qbits.standardprocesstrace.model;
 
 
 import java.util.List;
+import com.kingsrook.qbits.standardprocesstrace.utils.ProcessTraceSummaryLineRecordIntTableCustomizer;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.data.QField;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.data.QRecordEntity;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.FieldAdornment;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
@@ -78,6 +83,9 @@ public class ProcessTraceSummaryLineRecordInt extends QRecordEntity
             .withExposedJoin(new ExposedJoin().withLabel("Summary Line").withJoinPath(List.of(parentJoinName)).withJoinTable(ProcessTraceSummaryLine.TABLE_NAME))
             .withExposedJoin(new ExposedJoin().withLabel("Process Trace").withJoinPath(List.of(parentJoinName, grandparentJoinName)).withJoinTable(ProcessTrace.TABLE_NAME));
 
+         table.withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(ProcessTraceSummaryLineRecordIntTableCustomizer.class));
+         table.getField("recordId").withFieldAdornment(new FieldAdornment(AdornmentType.LINK).withValue(AdornmentType.LinkValues.TO_RECORD_FROM_TABLE_DYNAMIC, true));
+
          return (table);
       }
    }

src/main/java/com/kingsrook/qbits/standardprocesstrace/utils/ProcessTraceSummaryLineRecordIntTableCustomizer.java

@@ -0,0 +1,78 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qbits.standardprocesstrace.utils;
+
+
+import java.io.Serializable;
+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.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
+import com.kingsrook.qqq.backend.core.model.tables.QQQTable;
+import com.kingsrook.qqq.backend.core.processes.utils.GeneralProcessUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ProcessTraceSummaryLineRecordIntTableCustomizer implements TableCustomizerInterface
+{
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface queryInput, List<QRecord> records) throws QException
+   {
+      if(queryInput.getShouldGenerateDisplayValues())
+      {
+         ///////////////////////////////////////////////////////////////////////////////////////
+         // for records with a qqqTableId - look up that table name, then set a display-value //
+         // for the Link type adornment, to the recordId record within that table.            //
+         ///////////////////////////////////////////////////////////////////////////////////////
+         Set<Serializable> tableIds = records.stream().map(r -> r.getValue("qqqTableId")).filter(Objects::nonNull).collect(Collectors.toSet());
+         if(!tableIds.isEmpty())
+         {
+            Map<Serializable, QRecord> tableMap = GeneralProcessUtils.loadTableToMap(QQQTable.TABLE_NAME, "id", new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, tableIds)));
+
+            for(QRecord record : records)
+            {
+               QRecord qqqTableRecord = tableMap.get(record.getValue("qqqTableId"));
+               if(qqqTableRecord != null && record.getValue("recordId") != null)
+               {
+                  record.setDisplayValue("recordId:" + AdornmentType.LinkValues.TO_RECORD_FROM_TABLE_DYNAMIC, qqqTableRecord.getValueString("name"));
+               }
+            }
+         }
+      }
+
+      return (records);
+   }
+}

src/main/java/com/kingsrook/qbits/standardprocesstrace/utils/ProcessTraceTableCustomizer.java

@@ -0,0 +1,78 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qbits.standardprocesstrace.utils;
+
+
+import java.io.Serializable;
+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.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.AdornmentType;
+import com.kingsrook.qqq.backend.core.model.tables.QQQTable;
+import com.kingsrook.qqq.backend.core.processes.utils.GeneralProcessUtils;
+
+
+/*******************************************************************************
+ **
+ *******************************************************************************/
+public class ProcessTraceTableCustomizer implements TableCustomizerInterface
+{
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @Override
+   public List<QRecord> postQuery(QueryOrGetInputInterface queryInput, List<QRecord> records) throws QException
+   {
+      if(queryInput.getShouldGenerateDisplayValues())
+      {
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         // for records with a keyRecordQqqTableId - look up that table name, then set a display-value //
+         // for the Link type adornment, to the keyRecordId record within that table.                  //
+         ////////////////////////////////////////////////////////////////////////////////////////////////
+         Set<Serializable> tableIds = records.stream().map(r -> r.getValue("keyRecordQqqTableId")).filter(Objects::nonNull).collect(Collectors.toSet());
+         if(!tableIds.isEmpty())
+         {
+            Map<Serializable, QRecord> tableMap = GeneralProcessUtils.loadTableToMap(QQQTable.TABLE_NAME, "id", new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, tableIds)));
+
+            for(QRecord record : records)
+            {
+               QRecord qqqTableRecord = tableMap.get(record.getValue("keyRecordQqqTableId"));
+               if(qqqTableRecord != null && record.getValue("keyRecordId") != null)
+               {
+                  record.setDisplayValue("keyRecordId:" + AdornmentType.LinkValues.TO_RECORD_FROM_TABLE_DYNAMIC, qqqTableRecord.getValueString("name"));
+               }
+            }
+         }
+      }
+
+      return (records);
+   }
+}

src/main/java/com/kingsrook/qbits/standardprocesstrace/utils/RecentProcessTracesWidgetBuilder.java

@@ -0,0 +1,80 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package com.kingsrook.qbits.standardprocesstrace.utils;
+
+
+import com.kingsrook.qbits.standardprocesstrace.model.ProcessTrace;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.RecordListWidgetRenderer;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+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.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** factory/builder class, to create instances of RecordListWidgetRenderer for
+ ** specific tables and/or processes within a table.
+ *******************************************************************************/
+public class RecentProcessTracesWidgetBuilder
+{
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QWidgetMetaData buildWidget(String tableName)
+   {
+      QWidgetMetaData widgetMetaData = RecordListWidgetRenderer.widgetMetaDataBuilder(tableName + "RecentProcessTraces")
+         .withTableName(ProcessTrace.TABLE_NAME)
+         .withMaxRows(20)
+         .withLabel("Recent Process Traces")
+         .withFilter(new QQueryFilter()
+            .withCriteria("qqqTable.name", QCriteriaOperator.EQUALS, tableName)
+            .withCriteria("keyRecordId", QCriteriaOperator.EQUALS, "${input.id}")
+            .withOrderBy(new QFilterOrderBy("id", false))
+         ).getWidgetMetaData();
+
+      return (widgetMetaData);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   public static QWidgetMetaData buildWidget(String tableName, String processName)
+   {
+      QWidgetMetaData widgetMetaData = RecordListWidgetRenderer.widgetMetaDataBuilder(tableName + StringUtils.ucFirst(processName) + "RecentProcessTraces")
+         .withTableName(ProcessTrace.TABLE_NAME)
+         .withMaxRows(20)
+         .withLabel("Recent Process Traces")
+         .withFilter(new QQueryFilter()
+            .withCriteria("qqqProcess.name", QCriteriaOperator.EQUALS, processName)
+            .withCriteria("qqqTable.name", QCriteriaOperator.EQUALS, tableName)
+            .withCriteria("keyRecordId", QCriteriaOperator.EQUALS, "${input.id}")
+            .withOrderBy(new QFilterOrderBy("id", false))
+         ).getWidgetMetaData();
+
+      return (widgetMetaData);
+   }
+
+}

src/main/java/com/kingsrook/qbits/standardprocesstrace/utils/StandardProcessTracer.java

@@ -30,7 +30,6 @@ import java.util.List;
 import java.util.Map;
 import com.kingsrook.qbits.standardprocesstrace.StandardProcessTraceQBitConfig;
 import com.kingsrook.qbits.standardprocesstrace.model.ProcessTrace;
-import com.kingsrook.qbits.standardprocesstrace.model.ProcessTraceKeyRecordMessage;
 import com.kingsrook.qbits.standardprocesstrace.model.ProcessTraceSummaryLine;
 import com.kingsrook.qbits.standardprocesstrace.model.ProcessTraceSummaryLineRecordInt;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
@@ -55,6 +54,7 @@ import com.kingsrook.qqq.backend.core.model.session.QUser;
 import com.kingsrook.qqq.backend.core.model.tables.QQQTableTableManager;
 import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
 import com.kingsrook.qqq.backend.core.processes.tracing.ProcessTracerInterface;
+import com.kingsrook.qqq.backend.core.processes.tracing.ProcessTracerKeyRecordMessage;
 import com.kingsrook.qqq.backend.core.processes.tracing.ProcessTracerMessage;
 import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
@@ -170,7 +170,7 @@ public class StandardProcessTracer implements ProcessTracerInterface
    {
       try
       {
-         if(message instanceof ProcessTraceKeyRecordMessage keyRecordMessage)
+         if(message instanceof ProcessTracerKeyRecordMessage keyRecordMessage)
          {
             Integer keyTableId = QQQTableTableManager.getQQQTableId(QContext.getQInstance(), keyRecordMessage.getTableName());
 
@@ -297,12 +297,21 @@ public class StandardProcessTracer implements ProcessTracerInterface
 
                         for(Serializable primaryKey : processSummaryLine.getPrimaryKeys())
                         {
-                           Integer recordId = ValueUtils.getValueAsInteger(primaryKey);
-                           if(recordId != null)
+                           try
                            {
-                              recordIntList.add(new ProcessTraceSummaryLineRecordInt()
-                                 .withQqqTableId(qqqTableId)
-                                 .withRecordId(recordId));
+                              Integer recordId = ValueUtils.getValueAsInteger(primaryKey);
+                              if(recordId != null)
+                              {
+                                 recordIntList.add(new ProcessTraceSummaryLineRecordInt()
+                                    .withQqqTableId(qqqTableId)
+                                    .withRecordId(recordId));
+                              }
+                           }
+                           catch(Exception e)
+                           {
+                              /////////////////////////////////////////////////////////////////////
+                              // todo log (would be loud)?  or, let not be integer maybe better? //
+                              /////////////////////////////////////////////////////////////////////
                            }
                         }
                      }