Configurations

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.

Note: Application Configurations are scoped per application and per environment. Unlike Application Settings which provide standardized system-wide preferences, Configurations allow fully customizable schema definitions tailored to specific business requirements. New applications have no configurations by default unless explicitly created.

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

Important: The ability to modify configurations directly in production without code deployment is a powerful feature. Changes to configurations in build or QA environments must be intentionally migrated to production—there is no automatic synchronization.

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

Note: The system validates Config Json against the defined Config Schema before allowing save operations. Invalid JSON structures or schema violations will prevent configuration updates with descriptive error messages.

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

Type	Description	Use Case
string	Text values	Names, descriptions, regex patterns, URLs
number	Numeric values (float or integer)	Thresholds, quantities, percentages
integer	Whole number values	Counts, IDs, port numbers
boolean	True/false flags	Feature toggles, enable/disable flags
object	Nested JSON object with properties	Complex structures, table references
array	Ordered list of items	Multiple selections, lists of records
null	Null/empty value	Optional fields with no default
any	Any valid JSON value type	Dynamic or polymorphic data

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

Parameter	Description
type	Input type (typically "select" for table references)
dataModel	Name of the data model to query (e.g., "Screen", "Route", "User", custom models)
labelPath	Field path displayed in dropdown (supports nested paths with dot notation)
labelField	Primary field for label display
stateTracking	Tracking mode for selected values (typically "full" to store complete record data)
multiselect	Boolean flag: true for array of selections, false for single selection
selectFields	Array of field paths to include in the configuration JSON (supports nested fields)

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 articles: Application Settings, Data Model Custom Fields, GraphQL API Tree Browser, Screen Designer Bindings, Data Flow Operations, Package Management

7. Troubleshooting

• Issue: Cannot save configuration - schema validation error • Cause: Config Json does not conform to the defined Config Schema • Fix: Review the validation error message which indicates the specific schema violation. Verify that all required fields are present, data types match the schema, and nested structures follow the defined pattern. Use a JSON validator to check syntax before attempting to save.
• Issue: Configuration not appearing in GraphQL queries • Cause: Configuration may be in wrong environment or query syntax incorrect • Fix: Verify you are querying the correct environment (configurations are per-environment). Check the configuration name spelling exactly matches. Use the API Tree Browser to explore available ApplicationConfiguration queries.
• Issue: Table reference dropdown is empty • Cause: Referenced data model has no records or access permissions issue • Fix: Verify the data model specified in inputProps.dataModel contains records. Check that your user has permission to read from the referenced data model. Ensure the dataModel name is spelled correctly.
• Issue: Configuration changes not reflected in production • Cause: Configurations do not automatically replicate across environments • Fix: Manually update the configuration in the production environment, or include the configuration in a migration package and deploy to production. Remember that this non-replication is intentional to allow environment-specific configurations.
• Issue: Complex nested structure causing performance issues • Cause: Configuration JSON is excessively large or deeply nested • Fix: Consider breaking large configurations into multiple smaller configurations. Use GraphQL query selectFields to retrieve only necessary data. Cache configuration data in screen or flow state rather than querying repeatedly.
• Issue: Regex pattern in configuration not working as expected • Cause: Regex string may need escaping in JSON or pattern is incorrect • Fix: Store regex patterns as strings in configuration JSON. When using in flows or screens, ensure proper escaping for backslashes (use \\ instead of \). Test regex patterns outside Fuuz first, then add validation in flows to catch pattern errors.
• Issue: Unable to modify configuration - access denied • Cause: Only App Admins and Developers can create/modify configurations • Fix: Verify you have App Admin or Developer access type. End users and other access types cannot modify configurations even if they have roles. Contact your administrator to grant appropriate access.
• Issue: Need to rollback configuration to previous version • Cause: No automatic rollback feature available • Fix: Navigate to Data Management > Data Changes. Filter by ApplicationConfiguration data model and locate the configuration record. Review the change history to see previous JSON values. Copy the previous JSON value and manually update the configuration.
• Issue: Schema changes breaking existing Config Json • Cause: Modified schema no longer validates existing configuration data • Fix: Before modifying Config Schema, test with sample JSON to ensure compatibility. When schema changes are necessary, update Config Json simultaneously to maintain compliance. Consider creating a new configuration rather than modifying existing if significant schema changes are required.
• Issue: Configuration not included in package deployment • Cause: Configuration not selected for package inclusion • Fix: When creating packages, explicitly include configurations in the package definition. If using Module and Module Group, ensure all configurations within the module are selected. Verify package contents before deployment.

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

Version	Date	Editor	Description
1.0	2024-12-27	Fuuz Documentation Team	Initial Release

See Also

• App-Management
• Settings
• Convert-JSON-To-JSON-Schema
• JSON-Schema-Inputs
• Sequences

---

Source: support.fuuz.com