Wiki Spaces
Mantle Business Artifacts
Moqui Applications
Moqui Community
Moqui Framework
Page Tree
Moqui Framework


All Pages

Moqui Framework Features (through 2.0.0)

Moqui Framework gives you flexible tools to quickly create functional and secure applications.

Moqui Framework helps you build applications quickly and scale complex applications to hundreds of thousands of lines of efficient, well organized code instead of millions of lines of mess. Along the way you work on only what you care about, and let the framework take care of the rest.

  1. Moqui Framework Features (through 2.0.0)
    1. Big Ideas
    2. Flexible deployment
    3. Clustering Support
    4. Default Runtime
    5. Technical Features
    6. Developer Friendly API
    7. Security
    8. Performance Monitoring
    9. Resources
    10. Localization
    11. Web Environment
    12. User Management
    13. Common business data structures and seed data
    14. Entities (Database)
    15. Services
    16. XML Screens
    17. Tools Application
    18. Example Application

Big Ideas

Comprehensive: Moqui Framework is designed to provide comprehensive infrastructure for enterprise applications and handle common things so you can focus your efforts on the business requirements, whether it be for a multi-organizational ERP system, an interactive community web site, or even a bit of simple content with a few forms thrown into the mix.

Automatic Functionality: By using the tools and practices recommended for the framework you can easily build complex applications with most security and performance concerns taken care of for you.

No Code Generation: Moqui relies on dynamic runtime functionality to avoid the need for code generation. This keeps your development artifacts small and easy to maintain, not just easy to create.

True 3-Tier Architecture: Many modern frameworks have tools for database interaction and user interaction but you have to roll your own logic layer. Moqui has a strongly defined and feature rich logic layer built around service-oriented principles. This makes it easy to build a service library for internal application use, and automatically expose services externally as needed.

Flexible deployment

  • Tested to run in Java on Windows, OS X, Linux, etc
  • Multi-instance management (separate app server in container or VM, separate databases)
  • Database
    • Uses embedded H2 database by default
    • Comes with configuration for H2, Derby, PostgreSQL, MySQL, HSQL, Oracle, DB2, and SQL Server
    • Support for other databases usually with configuration only
  • Other data sources
    • Plugin in NoSQL and other data sources
    • OrientDB graph and document database supported OOTB (runs embedded by default)
  • Application Server
    • Uses embedded Bitronix BTM or Atomikos TransactionsEssentials for JTA and connection pool
    • JTA factory interface to plugin other transaction managers without a full J2EE container
    • Support for JTA transaction manager and XA-aware connection pool from application server through JNDI
    • Executable WAR file for command-line data loading and embedded Jetty servlet container
    • The same WAR file can be dropped in a servlet container like Tomcat or Jetty, or a more general app server like JBoss or Weblogic
  • Custom deployment (embedded, etc)
    • Use the supplied MoquiServlet, or write your own based on that example, or use something other than a servlet for non-web apps
    • Everything runs from an instance of the ExecutionContextFactory, so it is easy to include in custom apps or deploy through OSGi, Spring, etc
    • Specify runtime directory path and conf file location using file or System properties (java -D arguments)
  • Project Build
    • Build, test, and deploy with Gradle
    • Directory structure consistent with de-facto standards from Maven/Gradle/etc
    • Deploy and WAR tools also in Ant build file for convenience

Clustering Support

  • Various interfaces to plugin distributed system tools
  • Default implementation using Hazelcast (in moqui-hazelcast tool component) with single configuration for all cluster coordination made easy with secure auto-discovery and cluster joining
  • Distributed Entity (database) Cache Invalidation
  • Distributed background service executor
  • Distributed notification topic
  • Distributed cache (JCache)
  • Web (Servlet) session replication

Default Runtime

  • Moqui is designed to have a runtime directory that is separate from the framework and that makes up your applications and add-ons
  • To help you get started Moqui comes with a sample runtime directory
  • Sample configurations for development, staging, and production
  • Configurable "root" screen with sample HTML wrappers, login, menus, etc
  • Separate screens under root screen to support undecorated subscreens and the apps decorated with with header/footer/menus/etc
  • Various configuration options and examples for flexible deployment and overriding templates for screen macros, xml-actions, etc
  • Easy to include the runtime directory inside the deployed war file
  • Support <component>/lib and runtime/lib jar loading in a cached and extended/extensible ClassLoader

Technical Features

  • Uses Groovy for scripting and Freemarker for templates, plus other options and easy plugin for any you want
  • Uses JTA transaction management and JDBC connection pool from JNDI, or internally managed with Atomikos TransactionsEssentials, Bitronix BTM, or plug in any other
  • WebSocket support through JSR-356 API or Moqui notification framework
  • Manage incoming and outgoing email
  • Network push printing through CUPS print servers
  • Flexible resource access from files, JCR repository, and many others
  • JCR 2.0 (JSR-283) based content and artifact management for Apache JackRabbit or other JCR implementations
  • Implicit internationalization and easy database-driven localization
  • Cache management for framework and application resources with pluggable local or distributed javax.cache (JSR-107) implementations
  • Write-through per-transaction cache available for complex services to minimize database round-trips
  • Built-in profiling tools for framework artifacts including screens, services, and entities
  • Multi-instance management (one container or VM and one database per instance) with automation support for Docker, MySQL, etc
  • Logging using SLF4J
  • Built with Gradle, plus run and deploy tools included for Gradle and Ant
  • Spock and JUnit for unit and integration (service call and screen render) testing

Developer Friendly API

  • Execution Context with information about user and application context, and access to tools
  • Execution Context Factory used to get instances of the ExecutionContext and control the life cycle of the framework
  • Facades for easy access to all framework functionality
    • WebFacade for access to Servlet objects, parameter maps, etc
    • UserFacade for current user data, login/logout/authentication, etc
    • MessageFacade for general and error message management
    • L10nFacade for localization of text
    • Resource Facade for access to classpath, file, JCR, etc resources, and for running scripts and rendering templates (with caching for all)
    • LoggerFacade for general logging, especially for non-class code
    • CacheFacade for general caching, backed by ehcache
    • TransactionFacade for general JTA-type operations and tracking what is currently going on with transactions, where errors originated, etc
    • ScreenFacade for rendering screens using the ScreenRender interface
    • Service Facade for running local and remote services by definition
    • Entity Facade for database access


  • Comprehensive security with declarative authorization
    • Settings in the database, separate from implementation artifacts
    • Define run-time inheritable permissions for any artifact in the system
    • Both record level and implementation artifact level security
  • Protection from XSS and XSRF threats (uses JSoup HTML parser/cleaner)
  • Incorporates Apache Shiro, which is now used for all authentication in Moqui, by default through the MoquiShiroRealm
  • Other realms such as for LDAP or ActiveDirectory can be configured with shiro.ini
  • Permission model and checking for simple/flat permissions (to be used as an alternative to artifact authz)
  • Runs permission and role (UserGroup) checks through Shiro realm
  • User account and flexible password constraints and management
  • XML Screens can require authentication and/or encryption
  • XSRF protection by requiring encryption of input in body parameters
  • ESAPI web input canonicalization/filtering to protect against XSS attacks
  • Artifact stack and history tracking for each ExecutionContext instance (single web request, service call, etc)
  • Tracked artifacts currently include screen, transition, service, entity
  • Artifact Tarpitting based on configuration in db (see example ArtifactTarpit in ExampleSecurityData.xml)
  • Artifact Authorization based on configuration in db
    • Persists data about authz failures (in ArtifactAuthzFailure entity)
    • Support authorization checks through Shiro realm
    • Disable authz on data loading; command line and assumed to be safe
    • Handle direct service/entity calls through ArtifactGroupMember with pattern
    • For entity-implicit service calls just look for entity authz
    • Support authorization on subscreens even if no authz on parent screens, ie authz for EditExample even though not for ExampleApp or any other screens in that app
    • Record-level authorization (ArtifactAuthzRecord/Cond)
    • Authorization with a service (ArtifactAuthzService)

Performance Monitoring

  • ArtifactHit and ArtifactHitBin tracking for screen, screen-content, transition, service and entity (bin only)
  • Artifact hit data includes time to run, size of output (when available), date/time of hit, visit (session) the hit was in, etc
  • Skip artifact stats tracking based on a conditional expression
  • Lightweight "status" screen that can be used to see if server is running
  • Built-in profiling for high level artifacts
    • Monitors performance of screens, transitions, services, and entities
    • See a full call tree for the scope of an ExecutionContext (web request, independent service call, etc)
    • See a consolidated report with counts and stats for multiple runs of each artifact in a tree by use
    • See hot spots by own time, own plus child time, etc


  • Provides access to resources through various protocols, and extensible to add support for more
  • Simple API for running scripts and rendering templates
  • Caching for all resources, and for compiled scripts and templates
  • Interfaces you can implement for:
    • resource reference and access (ResourceReference)
    • template rendering (TemplateRenderer)
    • script running (ScriptRunner)
  • Resource references supported OOTB include:
    • Java Classpath (classpath://)
    • Moqui Component (component://)
    • JCR Content (content://) - JCR 2.0 (JSR-283) based content and artifact management with Apache JackRabbit
    • Java URL (http, https, file, ftp, jar)
  • Templates supported OOTB include:
    • FreeMarker (.ftl) templates (
    • GString (.gstring) templates (
    • WikiText for rendering of wiki markups including:
      • Confluence (.cwiki, .confluence)
      • MediaWiki (.mediawiki)
      • Textile (.textile)
      • TracWiki (.tracwiki)
      • TWiki (.twiki)
  • Scripting languages supported OOTB include:
    • Groovy script (.groovy)
    • JavaScript (with Rhino) (.js)
    • Moqui XML Actions (.xml)
      • Converts to Groovy code then compiles for good runtime performance
      • Embeddable in service definitions, screens, etc


  • Base language values used as the key for localized variation lookup in database
  • Localized messages/labels and entity fields
  • Automatic internationalization of literal and expanded strings in most places
  • Number and date/time parsing and formatting methods

Web Environment

  • WebFacade for easy API access to Servlet objects, parameter maps, etc
  • WebApp event actions for first-hit-in-visit, before-request, after-request, after-login, before-logout, after-startup, before-shutdown
  • For convenience web.requestParameters Map is automatically added to the context when it is initialized for the web (helps reduce dependency in code on web-specific stuff, ie ec.web.requestParameter references)
  • Can send Maps/Lists/etc to HTTP response as JSON string (Web Facade), example of this is in EditExample.xml
  • Servlet for FOP transform to PDF, etc
  • Easy mapping of path and HTTP request method to services for REST, examples of this in ExampleApp.xml

User Management

  • UserFacade for current user data, login/logout/authentication, etc
  • User preference management for predefined (with Enumeration records) or ad-hoc keys
  • UserGroup support, mostly for security, similar to the concept of security "role" (avoiding the term "role" because of its use in the Party data model)
  • UserGroup (ALL_USERS) that all users are automatically members of
  • In UserAccount userId is internal/sequenced and the username field is used for auth/login
  • Password reset email and forgot password form
  • Visitor tracking (automatic visitor ID in a cookie, separate from user)
  • Visit (session) tracking

Common business data structures and seed data

  • Enumerations and statuses with transitions
  • Units of measure with conversion, including currency
  • Geographic boundaries (legal and arbitrary) and points
  • Time periods

Entities (Database)

  • Entity Facade
    • Define your entities and go, no code to write and no redundancy
    • Java API or XML tags for a wide variety of queries and common operations
    • Event-Condition-Action rules to do things based on data changes
    • Data import and export tools, including for seed and other setup data
    • Configuration data documents based on database data available as nested maps or JSON
    • Automatic data feed to send data documents to services on data changes for search indexing, sending notifications, etc
    • Data search built on ElasticSearch for any database, resource, or other custom data
    • Support OOTB for H2, Derby, HSQL, PostgreSQL, MySQL (and Percona, MariaDB, etc), SQL Server, DB2, and Oracle
    • Easy to add support for other databases, usually just through configuration
    • Support for plugging in other data sources
    • Built-in support for the OrientDB graph and document database
    • Time-based data synchronization support between Moqui systems
  • Entity Definition
    • Extension of other entities
    • Entity field audit-logging
    • Entity field encryption
    • Automatic reverse-many relationship for type one relationships coming the other way (done on-demand at run-time)
    • Database-driven view entity
    • view-entity: merge the view-link element into the member element (also for DynamicViewEntity, DbViewEntity, *DbView screens)
    • More intelligent group by fields, ie add all fields in view-entity and DynamicViewEntity to group by list if they don't have a function; with support for this get rid of alias.@group-by attribute, not needed when done automatically
  • EntityValue object with support for create, update, delete, refresh db operations, find related, various get and set options
  • Primary and secondary sequenced ID generation
    • Simplified sequenced ID API for both primary and secondary sequenced IDs and moved configuration to entity definition, and methods to EntityValue
    • Primary sequenced ID banking for better performance when creating records with sequenced single field primary key (default bank size 50)
  • Entity Find (Query)
    • EntityFind object with various conditions, etc supported and results of one, list, iterator, count, updateAll, or deleteAll
    • Support search-form-inputs to automatically populate an entity find from form *-find fields
    • Entity Cache support
    • Automatic cache clearing for one, list (using RA cache), count caches
    • Support offset and limit as LIMIT/OFFSET or OFFSET/FETCH depending on configuration on the database element in the Moqui conf file
    • Manual SQL find with results mapped to entity with results returned in an EntityListIterator (EntityFacade.sqlFind())
  • Database meta-data maintenance
    • Automatically creates tables at runtime as they are used (checks entities once per server start, if configured to do so)
    • Support for adding indexes when tables added
    • Automatically add columns if missing in table check
    • Add foreign keys to existing tables when table created
    • Can check the foreign keys of all entities with existing tables and add missing ones where both tables exist; useful to run once all desired tables have been created (through a data load, test script, etc) to round out the DB meta-data
  • Comprehensive data loader from entity XML files with API and command-line access
  • Entity export to XML
  • Entity Master data export (master record and all dependent records)
  • Entity ECA rules to trigger services on entity operations
  • Data Documents
    • Generates JSON (or nested Map/List) data documents based on database data
    • Data document and mapping to entities configured in simple database records for ad-hoc or preconfigured use
  • Data Feed
    • Automatically generates documents when database records change and sends them to services
    • Easy to setup data document indexing by sending to OOTB service
  • Data Search
    • Search Data Documents by search string and/or named fields in the document
    • Based on ElasticSearch (which is based on Apache Lucene)


  • Service Facade
    • Call services synchronously, async, or scheduled
    • Local async service run with java.util.concurrent.ThreadPoolExecutor
    • Distributed async services run with pluggable java.util.concurrent.ExecutorService implementation
    • Scheduled service jobs run with java.util.concurrent.ScheduledThreadPoolExecutor, configured with extended Cron strings
    • Services can be local or remote and implemented in a variety of languages
    • Flexible XML service definitions
    • Validation of data type, required or not, regexp, and other constraints; validation runs on server and in client with JavaScript library
    • Event-Condition-Action (ECA) rules to orchestrate high level processes, externally change or augment behavior of existing services, and much more
    • Native integration with Apache Camel for flexible and powerful integration with other systems and applications
    • System-to-System Message management for producing/sending and receiving/consuming
  • Service Definition
    • Service parameter type/subtype checking
    • Service parameter conversion/parsing and validation checks
    • Service parameter HTML checking and cleaning (any/safe/none) with Jsoup
    • Service authentication
    • Service expand auto-parameters, get parameters from implements
    • Automatic (with no definition) entity-based services for create, update, delete and store (create or update)
  • Service running
    • Call services synchronously in thread with minimal overhead
    • Call services async or scheduled (uses Quartz Scheduler)
    • Support of pre-configured scheduled job exists, see:
    • Service run on commit or rollback of current tx
    • Service Event-Condition-Action (ECA) rules to trigger other services before validation, auth, service run, or after service run or commit, or when the tx is actually committed or rolled back
    • Service runners for Java, XML Actions, inline actions, Scripts
    • Interface for adding your own service runners
  • Write-through per-transaction cache available for complex services to minimize database round-trips
  • Email handling
    • Incoming email handling with Email ECA Rules (emeca) with the org.moqui.impl.EmailServices.pollEmailServer service, configured with the EmailServer entity
    • Service (org.moqui.impl.EmailServices.sendEmailTemplate) to send email based on settings in the EmailTemplate entity
  • Web Services
    • REST web services with minimal configuration for internal service mapping
    • Generic RESTful data interface based on entity definitions, secure with authc and authz
    • JSON-RPC 2.0 incoming service handler and outgoing service runner
    • XML-RPC incoming service handler and outgoing service runner (with Apache XML-RPC)
  • Apache Camel endpoint for receiving messages to call Moqui services, or defining services that call into Camel
  • JBoss Drools KIE Support
    • Easily use Drools rules in your business logic
    • Use jBPM workflows for easier control and monitoring of business processes

XML Screens

  • Screen Facade
    • Declarative multi-platform screens, text templates, or any combination
    • Generate HTML, XML, PDF (XSL-FO), CSV, Fixed-width plain text, or drive GWT or Swing screens
    • Screen files and included sets of subscreens in directories with the same structure as the application
    • Nested subscreens for multiple levels of tabs or other types of menus
    • Data preparation logic declared with screens to make each screen modular
    • Outgoing transitions point to input processing logic and conditional forwarding to other screens or external URLs
    • Forms (single, list), trees, panels, and various other common widgets
  • Screen Definition
    • Subscreens hierarchical to any depth, URL "path info" is path to screen in hierarchy
    • Screen menus automatically generated based on sub-screens
    • Choose default subscreen (override by path) based on user agent or other condition (using any data available in the ec)
    • Sub-screens by directory structure, XML elements, or database record
    • Screens and sub-content can be located in files or in a JCR repository
    • Screen sub-content (stand-alone or included in screen) including support for text and binary files and all template types supported by the Resource Facade
    • Can include or inline HTML and other text content
    • Standalone screens that are rendered independently of parent screens and can still be subscreens of any other screen
    • Support for multiple root screens determined by host name using regexp, or in other words virtual host support
    • Screen transition supports restriction by HTTP request method
    • Dynamic transition name handling (support regex transition names)
    • Override login path in screen (use value from deepest screen in path)
    • Screen pre-actions that all run before any parent screen is rendered to allow for setting parameters in parent screens, setting up general things, etc
    • Database-driven screen visual themes
    • Output encoding, configurable on various screen/form elements
    • Includes container-dialog widget that creates a button that when clicked on opens a dialog with the contents of the container-dialog.
  • Screen Rendering
    • ScreenFacade for rendering screens using the ScreenRender interface
    • Templates for various render modes:
      • csv (mainly for form-list report-like output)
      • text (for email alternative message, etc)
      • xml (like CSV, but more structured and support multiple forms per screen)
      • xsl-fo (generate PDF or other FOP output types)
    • URL building based on configuration
    • Can specify macro template in screen def to override default in moqui-conf
    • Supports URL parameters for renderMode and pageNoLimit which along with the lastStandalone parameter make it easy to reuse screens and forms meant for user interaction as definitions for CSV output
    • Screen subscreen menu dynamic tabs (last level only) that loads content as a standalone screen from the server with an ajax call
    • Default runtime includes jquery and jquery-ui and the smoothness and dot-luv themes (easy to add others or make your own)
    • Automatic I18n (with L10nFacade) for labels and titles in screens, forms, menus
  • Screen Forms
    • Single forms (form-single)
      • For editing a single record (or single set of fields across records)
      • Manual field-layout support
      • Default HTML uses fieldset and label instead of a table
    • List forms (form-list)
      • For editing or viewing multiple records (or multiple sets of fields across records)
      • Explicit form-list-column support
      • Pagination (with defaults in search-form-inputs)
      • multi=false support (one form per row)
      • multi=true support (one form for all rows), service call multi=true
      • Header widget rendering
      • Automatic sort order links in header
    • Extend XML form definitions with database records for all users or specific groups
    • Form field types for many common form widgets
    • Auto-complete option for text-line field type
    • Form focus-field, skip-start and skip-end supported
    • Automatic form fields from entity and service definitions
      • Client JS validation based on target transition service definition (define once, run on client and server); using jquery validation (; so far for required, number-integer, number-decimal, text-email, text-url, text-digits, credit-card, regexp; try out on the Edit Example screen
      • Auto create drop-downs for fields with a relationship to Enumeration using relationship.title as the enumTypeId, check to see if is valid enumTypeId before creating drop-down
      • Auto create drop-downs for fields with a type one relationship, with limit of 200 to avoid crazy drop-downs
    • Localized output formatting, based on service parameter format if applicable, otherwise on format specified in form field
    • Includes datetimepicker, which is the standard jquery datepicker plus the timepicker add-on, combined using some code from Apache OFBiz

Tools Application

  • Auto Screen
    • Screens generated automatically based on the data model with a find screen and a screen for each "master" entity (an entity with dependents) with tabs for each dependent entity
    • There are two main types of dependent entities: "detail" entities with additional information about the master and "join" entities that go between two master entities
    • Master Entity List: use autocomplete box to select any entity or select a master entity from the list
    • AutoFind Screen (find, create, delete master entity records)
    • AutoEditMaster (tab to edit master entity record)
    • AutoEditDetail (tab for each dependent entity (detail and join entities) with CrUD)
    • Order by links in column headers by default (by default for all auto fields entity as well)
  • Data Document
    • A Data Document is a JSON document (or nested Maps/Lists) based on data from databases and structured as defined for the document in configuration records
    • Trigger document indexing
    • Export data documents
    • Search data documents across various indexes, view the documents, and link to application screens for the documents
  • Data View
    • Choose master entity, select fields from all related entities, save as DbViewEntity and related records
    • Specify functions for selected fields
    • Choose column(s) to order by
    • Specify search constraints
    • View in webapp
    • Export to CSV
  • Service
    • Select service and run from form based on service definition
  • Entity
    • Entity Data UI
      • entity list
      • find on entity with delete
      • create/update entity record
      • view entity record with related entities and links to them
    • Entity Data Import from file, directory, configured file set, or web form
    • Entity Data Export with entity select, dependents option, date range, filter map, sort order
    • SQL Query Runner
  • System Info
    • Artifact Hit Bins and Summary report
    • Audit Log
    • Visit and Hit Info/Stats (Find Visits, Visit details with hit list)
    • Cache List and Elements
    • Localization: Messages, Entity Fields

Example Application

  • Example application with screens, sub-content (CSS, html.ftl, cwiki.ftl), entities and services, security, l10n data, etc
  • Example entities and seed data follow pattern used in Moqui and Mantle where the relationship.title is the enumTypeId or the statusTypeId