JSON Form Fields in Action Steps

JSON Form Fields in Action Steps

Article Type: Configuration / How-To Audience: Application Designers, Developers, Partners Module: Screen Designer Applies to Versions: 2024.1+ Estimated Time: 15-20 minutes

1. Overview

JSON Form Fields provide a quick and efficient way to create simple modal popup forms without designing a full screen. By defining form inputs using JSON configuration within action steps, you can rapidly build create and edit dialogs for your end users. This approach is ideal for straightforward data entry scenarios requiring only basic inputs in a single-column layout.

JSON Form Fields are typically used in action button configurations and table column menu features, allowing you to define popup forms directly within the action definition rather than creating separate screen designs.

Note: This approach is best suited for simple, single-record operations with a few basic inputs. For complex workflows, nested mutations, multi-step processes, or advanced layouts, use Screen Dialogues or dedicated form screens instead.

2. Prerequisites

• Access Type: App Admin or Developer
• Permissions: Screen design and deployment permissions
• Knowledge: Basic understanding of JSON syntax and Fuuz data models
• Resources: A screen with action buttons or table column menus configured

3. Choosing the Right Approach

Fuuz offers multiple ways to present forms to users. Understanding when to use each approach ensures optimal user experience and maintainability.

Comparison: JSON Form Fields vs. Screen Dialogues

Aspect	JSON Form Fields (Form Action)	Screen Dialogue
Best For	Quick, simple forms with few fields	Complex workflows, advanced layouts, multi-step processes
Layout	Single column only	Full canvas control (multi-column, sections, tabs)
Input Types	Text, number, date, datetime, time, select, multiline, markdown	All input types plus charts, tables, visualizations, custom components
Data Operations	Simple mutations (single record create, edit, delete)	Complex mutations, nested records, mass creates, web flows
Workflow Integration	Limited to simple action steps	Full web flow integration, conditional logic, multi-step approvals
Setup Time	Minutes (JSON configuration)	Longer (full screen design)
Reusability	Embedded in action (less reusable)	Separate screen (highly reusable across multiple actions)
Action Type	Form	Screen Dialogue

Use JSON Form Fields When:

• You need only a few basic input fields (typically 1-6 fields)
• The operation is a simple single-record create, edit, or delete
• No complex validation logic or conditional field visibility is required
• You want rapid development without creating separate screen assets
• The form doesn't require charts, tables, or rich visualizations

Use Screen Dialogues When:

• You need multi-column layouts or complex formatting
• The workflow involves web flows or multi-step processes
• You require supervisor signoffs or approval chains
• The form includes nested mutations or mass record operations
• You need conditional field visibility or complex validation
• The modal requires charts, tables, or other visualizations
• The form will be reused across multiple screens or actions

Tip: When using web flows for complex workflows and modals (such as supervisor signoffs), always use Screen Dialogues or separate screen designs. This provides the flexibility needed for proper workflow orchestration and error handling.

4. Procedure Steps

Step 1: Navigate to the Screen Designer

1. Open the Screen Designer application.
2. Open or create the screen where you want to add the popup form.

Step 2: Add an Action Trigger

Select or add an element that will trigger the popup form:

1. Add an Action Button to your screen, or
2. Configure a Column Menu action in a table, or
3. Use an existing action element.

Step 3: Configure the Form Action

1. Select the action element and open its properties panel.
2. Add a new action step.
3. Select the "Form" action type from the dropdown.
4. Provide a Name for your form — this displays as the modal title to end users (e.g., "Create New Item", "Edit Record", "Add Comment").

Step 4: Define Form Fields Using JSON

1. Locate the Form Fields section in the action configuration.
2. Click the four-way arrow icon above the Form Fields section to open the full-screen editor.
3. Define your form fields using the JSON array structure.

Basic Text Input Example:

[
  {
    "name": "name",
    "description": "Enter the item name",
    "label": "Name",
    "type": "text",
    "dataPath": "name",
    "disabled": false,
    "validation": {
      "required": true
    },
    "defaultValue": "",
    "query": {
      "fields": ["name"]
    }
  }
]

Step 5: Add Multiple Fields

Add additional field objects to the array, separated by commas:

[
  {
    "name": "name",
    "label": "Name",
    "type": "text",
    "dataPath": "name",
    "validation": { "required": true }
  },
  {
    "name": "description",
    "label": "Description",
    "type": "multiline",
    "dataPath": "description",
    "validation": { "required": false }
  },
  {
    "name": "quantity",
    "label": "Quantity",
    "type": "number",
    "dataPath": "quantity",
    "defaultValue": 1,
    "validation": { "required": true }
  },
  {
    "name": "dueDate",
    "label": "Due Date",
    "type": "date",
    "dataPath": "dueDate",
    "validation": { "required": false }
  }
]

Step 6: Save and Test

1. Close the full-screen editor.
2. Save your screen design.
3. Deploy to test environment.
4. Test the action to verify the popup form displays correctly.

5. Configuration Reference

Field Properties

Property	Required	Description
name	Yes	Unique identifier for the field; should match your data model field name
label	Yes	Display label shown to the user
type	Yes	Input type (see Available Field Types below)
dataPath	Yes	Path to the data model field to update
description	No	Help text displayed to users (often shown on hover or in help mode)
disabled	No	Set to true to make field read-only; default is false
defaultValue	No	Initial value for the field; user can change unless disabled
validation	No	Validation rules object (e.g., { "required": true })
query	No	Query configuration specifying which data model fields to include

Available Field Types

Type	Description	Use Case
text	Single-line text input	Names, titles, short text
multiline	Multi-line text area	Descriptions, notes, comments
markdown	Markdown-enabled text editor	Rich text content, formatted documentation
number	Numeric input	Quantities, amounts, counts
date	Date picker (date only)	Due dates, effective dates, birthdays
datetime	Date and time picker	Scheduled events, timestamps, appointments
time	Time picker (time only)	Shift times, daily schedules
select	Dropdown selection	Status, category, predefined options
color	Color picker with color wheel	Status colors, category colors, UI display colors

Color Input Example

The color input type provides a color wheel picker for users to select hex color values. This is useful for allowing end users to configure display colors for statuses, categories, or other UI elements.

{
  "name": "color",
  "description": "Color to be used in UI for display purposes",
  "label": "Color",
  "type": "color",
  "disabled": false,
  "dataPath": "color",
  "validation": {
    "required": false
  },
  "defaultValue": "#cccccc",
  "query": {
    "fields": ["color"]
  }
}

Tip: Color inputs store hex color codes (e.g., #FF5733). You can use these values directly in conditional formatting for table cells, status indicators, or any UI element that supports color styling.

Note: Additional field type examples and configurations will be provided in future article revisions. For complex input requirements, consider using Screen Dialogues with full canvas-based screen design.

Using Transforms in JSON Forms

You can incorporate dynamic behavior into JSON form fields using stringified transforms:

• Pre-transforms in the action: apply transforms before the form displays to calculate default values or modify field configurations.
• Embedded transforms in form elements: include transforms directly within field properties for dynamic behavior based on context or access.

6. Use Case Examples

Example 1: Quick Create Form (Use JSON Form Fields)

Scenario: Add a "Create New Task" button to a task list table that opens a simple form with name, description, and due date.

Why JSON Form: Only 3 fields, single record creation, no complex workflow, no conditional logic.

[
  {
    "name": "name",
    "label": "Task Name",
    "type": "text",
    "dataPath": "name",
    "validation": { "required": true }
  },
  {
    "name": "description",
    "label": "Description",
    "type": "multiline",
    "dataPath": "description"
  },
  {
    "name": "dueDate",
    "label": "Due Date",
    "type": "date",
    "dataPath": "dueDate"
  }
]

Example 2: Quick Edit from Table Row (Use JSON Form Fields)

Scenario: Column menu action to quickly edit a record's status and notes directly from the table.

Why JSON Form: Simple edit operation, 2 fields, no workflow integration needed.

Example 3: Supervisor Approval (Use Screen Dialogue)

Scenario: An approval workflow that requires supervisor signature, comments, displays related documents, and triggers notifications.

Why Screen Dialogue: Requires web flow integration, displays additional data (documents), has conditional logic based on approval outcome, involves multiple related records.

Example 4: Batch Record Creation (Use Screen Dialogue or Separate Screen)

Scenario: Import or create multiple inventory items at once with validation against existing records.

Why Screen Dialogue/Separate Screen: Mass create operations, nested mutations, complex validation requirements exceed modal scope.

Example 5: Multi-Step Order Entry (Use Separate Screen)

Scenario: Order entry requiring customer selection, multiple line items, shipping configuration, and payment processing.

Why Separate Screen: Complexity exceeds what a modal should handle; requires tables for line items, multiple sections, and extensive workflow logic.

7. Troubleshooting

Issue	Cause	Solution
Form doesn't display	JSON syntax error in form fields configuration	Validate JSON structure; check for missing commas, brackets, or quotes
Data not saving	Incorrect dataPath or name doesn't match data model	Verify field names match your data model exactly (case-sensitive)
Field type not rendering correctly	Invalid or unsupported type value	Use supported types: text, multiline, markdown, number, date, datetime, time, select
Validation not working	Incorrect validation object structure	Ensure validation is an object: "validation": { "required": true }
Default value not appearing	Existing record data overrides default	Default values apply to new records; existing records use their current values
Need more complex layout	JSON Form Fields only support single-column layout	Use Screen Dialogue action type to open a fully designed screen as a modal

8. Revision History

Version	Date	Editor	Description
1.0	2023-10-09	Fuuz Documentation Team	Initial Release - Text input example
2.0	2025-01-11	Fuuz Documentation Team	Added comparison guide, field types reference, use cases, and Screen Dialogue guidance

See Also

• Mobile-Screen-Design-Standard
• Setup-Data-Table-Screen-Design-Standard
• Master-Data-Table-Screen-Design-Standard
• Manage-what-displays-in-Field-Level-Help-throughout-Fuuz

---

Source: support.fuuz.com