Application Configurations

Article Type: Concept
Audience: App Administrators, Application Designers, Developers
Module: App Management
Applies to Versions: All Versions

1. Overview

Application Configurations provide a flexible, schema-validated system for defining custom configuration data that extends beyond standard Application Settings. This feature enables App Administrators and Developers to create enterprise-grade solutions where business logic can be abstracted from application logic, allowing configuration changes in production environments without code deployment. Configurations support complex nested JSON structures with validated references to system and custom data models, making them ideal for multi-site deployments, dynamic workflows, and adaptable business rules.

2. Architecture & Data Flow

Definitions

• Configuration: A named, schema-validated JSON document that stores custom application settings and business logic parameters.
• Config Schema: A JSON Schema definition that validates the structure, data types, and constraints for the configuration's JSON data. Determines what fields are available, their types, validation rules, and input mechanisms.
• Config Json: The actual configuration data blob containing the JSON structure and values that conform to the defined Config Schema.
• Module: An organizational category that associates configurations with specific functional areas within an application (e.g., Quality, Testing, Orchestration).
• Module Group: A higher-level organizational category that groups related modules together for packaging and deployment purposes.
• Table Reference: A schema property that creates validated dropdown selections from system or custom data models, ensuring configuration values reference valid records.
• Input Props: Schema properties that define how configuration fields are presented and validated in the user interface.

Components

• Configuration Definition: Name, Description, Module, Module Group metadata
• Schema Validator: JSON Schema engine that enforces data type and structure validation
• GraphQL API: Standard query interface for accessing configurations from screens, flows, and integrations
• Data Change Tracking: Audit system capturing configuration modifications
• Package System: Migration mechanism for deploying configurations across environments

Configuration Scope

• Per Application: Each custom application maintains independent configuration definitions
• Per Environment: Configurations exist separately in build, QA, and production environments
• Per Tenant: Configuration data is tenant-specific (accessible cross-tenant via API if needed)
• No Auto-Replication: Configuration changes do not automatically propagate across environments
• Package Migration: Configurations can be included in application packages for controlled deployment

3. Use Cases

• Multi-Site Manufacturing Logic: Abstract site-specific business rules (e.g., material issuing processes that differ across plants) into configurations, allowing each site to operate with different logic while maintaining consistent application code.
• Dynamic Document Printing Workflows: Configure document printing rules that vary by plant, department, or customer without deploying new flows. Store printer selections, document templates, and routing logic in configurations.
• Production-Adjustable Scanning Patterns: Expose regex patterns or validation rules for barcode/RFID scanning applications in configurations, enabling production adjustments without flow redeployment.
• Menu and Navigation Customization: Define parent-child screen relationships and navigation structures that can be adjusted per customer or deployment scenario.
• Integration Endpoint Management: Store API endpoints, authentication credentials, and integration parameters that differ between environments or customers in validated configurations.
• Regional Timezone and Locale Rules: Configure complex timezone handling, shift schedules, or regional business rules that go beyond standard Application Settings.
• Workflow State Machine Definitions: Define approval workflows, state transitions, or business process rules in configuration JSON that can be modified without code changes.
• Module Packaging: Bundle complete functional modules (screens, flows, schema, documents, configurations) as packages for deployment across applications or tenants.

4. Screen Details

The Application Configurations screen is accessed via App Management > Configurations in the App Admin menu section.

Configurations Table

The main table displays all available configurations with the following columns:

• Name: Configuration identifier (clickable link to configuration details)
• Description: Explanation of the configuration's purpose and usage context
• Config Schema: JSON Schema definition preview (expandable to view full schema)
• Config Json: Configuration data preview (expandable to view full JSON)
• Module: Functional area association (filterable)
• Module Group: Higher-level grouping category (filterable)

Available Actions

• Search: Filter configurations by name or description
• Create New Configuration: Define a new configuration with schema and initial JSON values
• Edit Configuration: Modify schema definition or JSON data (schema changes are validated before save)
• Delete Configuration: Remove a configuration (use with caution if referenced by screens or flows)
• Filter by Module: Display only configurations associated with a specific module
• Filter by Module Group: Display only configurations within a specific module group

Configuration Editor

When creating or editing a configuration, the following fields are available:

• Name: Required unique identifier for the configuration
• Description: Optional explanation of configuration purpose and usage
• Module: Optional module association for organizational purposes
• Module Group: Optional module group for packaging and deployment
• Config Schema: JSON Schema editor with syntax validation
• Config Json: JSON data editor with schema validation

5. Technical Details

JSON Schema Structure

Config Schema uses standard JSON Schema format with Fuuz-specific extensions for UI rendering and data model integration.

Supported Field Types

Table References (Lookups)

Table references create validated dropdown selections from system or custom data models. When a user configures a field with a table reference, they select from actual records in the specified data model.

Input Props for Single Selection:

{
  "type": "object",
  "inputProps": {
    "type": "select",
    "dataModel": "Screen",
    "labelPath": "name",
    "labelField": "name",
    "stateTracking": "full",
    "multiselect": false,
    "selectFields": ["id", "name", "description"]
  }
}

Input Props for Multi-Selection:

{
  "type": "array",
  "items": {},
  "inputProps": {
    "type": "select",
    "dataModel": "Route",
    "labelPath": "title",
    "labelField": "title",
    "stateTracking": "full",
    "multiselect": true,
    "selectFields": ["id", "title", "path", "screen.active", "screen.name"]
  }
}

Input Props Parameters

Embedded Options (User-Defined Lists)

Instead of table references, you can define embedded option lists that are validated within the configuration context only:

{
  "type": "string",
  "enum": ["Option1", "Option2", "Option3"]
}

Required and Default Values

Use standard JSON Schema keywords to define required fields and defaults:

{
  "type": "object",
  "properties": {
    "requiredField": { "type": "string" },
    "optionalField": { "type": "string", "default": "defaultValue" }
  },
  "required": ["requiredField"]
}

Accessing Configurations

Application Configurations are accessible via standard GraphQL queries throughout the Fuuz platform.

From Screens (JSONata Bindings)

Use GraphQL queries in screen data sources or component bindings to retrieve configuration data:

query {
  ApplicationConfiguration(name: "Mobile Menu Configuration") {
    configJson
  }
}

From Data Flows

Query configurations in flow nodes using GraphQL operations to retrieve configuration data for transformation or routing logic.

From Web Flows

Access configurations via GraphQL queries in web flow nodes to dynamically adjust API responses or business logic based on configuration values.

From External Integrations

Use the Fuuz GraphQL API endpoint to query configurations from external systems. Cross-tenant access is available via API if needed.

Complete Example Configuration

Use Case: Mobile menu configuration that defines parent screens and their associated child screen routes.

Configuration Metadata:

• Name: Mobile Menu Configuration
• Description: Defines parent-child screen relationships for mobile navigation menu
• Module: Testing
• Module Group: System

Config Schema:

{
  "type": "object",
  "properties": {
    "screens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "parentScreen": {
            "writeOnly": false,
            "readOnly": false,
            "deprecated": false,
            "examples": [],
            "minProperties": 0,
            "inputProps": {
              "type": "select",
              "dataModel": "Screen",
              "labelPath": "name",
              "labelField": "name",
              "stateTracking": "full",
              "multiselect": false,
              "selectFields": ["id", "name", "description"]
            },
            "type": "object"
          },
          "childScreens": {
            "writeOnly": false,
            "readOnly": false,
            "deprecated": false,
            "examples": [],
            "minItems": 0,
            "uniqueItems": false,
            "inputProps": {
              "type": "select",
              "dataModel": "Route",
              "labelPath": "title",
              "labelField": "title",
              "stateTracking": "full",
              "multiselect": true,
              "selectFields": [
                "id", "title", "path",
                "screen.active", "screen.name"
              ]
            },
            "type": "array",
            "items": {}
          }
        }
      }
    }
  }
}

Config Json:

{
  "screens": [
    {
      "parentScreen": {
        "id": "mobileHomeTemplateScreen",
        "name": "Mobile Home Template Screen",
        "description": ""
      },
      "childScreens": [
        {
          "id": "cmfy3xugo0cyv014vfb6443fg",
          "title": "Gateway Dashboard",
          "path": "/system/testing/gatewayDashboard",
          "screen": {
            "active": true,
            "name": "Gateway Dashboard"
          }
        },
        {
          "id": "cmfy3bjqp0bc80149gruo1g92",
          "title": "Application Dashboard",
          "path": "/system/testing/applicationDashboard",
          "screen": {
            "active": true,
            "name": "Application Dashboard"
          }
        }
      ]
    }
  ]
}

Accessing in Screen:

/* GraphQL Query in Screen Data Source */
query {
  ApplicationConfiguration(name: "Mobile Menu Configuration") {
    configJson
  }
}

/* JSONata to extract child screens for first parent */
$config := $ApplicationConfiguration.configJson;
$config.screens[0].childScreens

6. Resources

• JSON Schema Documentation
• Related KB Article: Application Settings
• Related KB Article: Data Model Custom Fields
• Related KB Article: GraphQL API Tree Browser
• Related KB Article: Screen Designer Bindings
• Related KB Article: Data Flow Operations
• Related KB Article: Package Management

7. Troubleshooting

Best Practices

• When to Use Configurations vs Settings: Use Application Settings for standardized, system-wide preferences like date formats and themes. Use Application Configurations for custom business logic, complex nested structures, and application-specific rules that vary by deployment.
• When to Use Configurations vs Data Models: Use Configurations for application logic and rules that are maintained by administrators. Use Data Models for transactional data that is created, updated, and queried by end users.
• Naming Conventions: Use descriptive names that indicate purpose and scope (e.g., "Production Line Material Issuing Rules", "Document Print Routing Configuration"). Avoid generic names like "Config1" or "Settings".
• Schema Design: Define comprehensive schemas with appropriate field types, required fields, and validation rules before populating Config Json. Well-designed schemas prevent configuration errors and improve maintainability.
• Module Organization: Assign meaningful Module and Module Group values to enable logical organization and packaging. Group related configurations together for easier maintenance and deployment.
• Documentation: Use the Description field to thoroughly document the configuration's purpose, expected structure, and how it is referenced in the application. Include examples of valid Config Json.
• Testing Strategy: Test configuration changes in build or QA environments before applying to production. Verify that screens, flows, and integrations correctly consume the configuration data.
• Version Control: Before making significant changes to configurations, document the current state or take screenshots. Use Data Change History as a rollback reference if needed.
• Production Changes: Leverage the ability to modify configurations in production for rapid adjustments, but establish a change approval process to prevent unintended impacts.
• Performance Optimization: Cache configuration data in screen or flow variables when accessed repeatedly. Use GraphQL selectFields to retrieve only necessary data rather than entire configuration JSON.
• Table Reference Fields: When using table references in schemas, select only the fields needed in selectFields to minimize data payload and improve query performance.
• Avoid Hardcoding: Use configurations instead of hardcoding business rules in flows or screens. This approach enables production adjustments without code deployment.
• Migration Planning: When promoting applications between environments, include configurations in packages or maintain a checklist of manual configuration updates needed in each environment.

8. Revision History