Form Builder User Guide

Form Builder and Rules Builder User Guide

Table of Contents

1. Overview
2. Accessing the Form Builder
3. Form Builder Interface
4. Managing Form Sections (Tabs)
5. Managing Form Fields
6. Field Types Reference
7. Dropdown Field Choices
8. Field Validations
9. Rules Builder
10. Import and Export
11. Factory Reset
12. Common Use Cases
13. Best Practices
14. Troubleshooting

---

Overview

The Form Builder is a powerful administrative tool that allows you to customize the forms used throughout RegScale. You can add custom fields, reorganize sections, create conditional logic with rules, and tailor forms to match your organization's specific workflow requirements.

Key Capabilities

• Customize Module Forms: Modify forms for vulnerabilities, risks, issues, assets, and other modules
• Add Custom Fields: Create new fields specific to your organization's needs
• Organize Sections: Add, remove, or reorder form tabs and fields
• Create Conditional Logic: Build rules that show/hide fields, set values, or change requirements based on conditions
• Import/Export Configurations: Share form configurations across environments or back up your customizations
• Factory Reset: Restore forms to their default configuration when needed

Prerequisites

• Administrator Role: Only users with Administrator privileges can access the Form Builder
• Understanding of Your Workflow: Know what information your team needs to capture
• Familiarity with RegScale Modules: Understanding of vulnerabilities, risks, issues, etc.

---

Accessing the Form Builder

Navigation Path

1. Log in to RegScale with an Administrator account
2. Click on Admin in the main navigation menu
3. Select Form Builder from the admin panel

Selecting a Module

Once in the Form Builder, you'll see a dropdown at the top to select which module's forms you want to customize:

• Assets
• Catalog Templates
• Catalogs
• Components
• Control Implementations
• Evidence
• Issues
• Policies
• Risks
• Security Controls
• Security Plans
• Tasks
• Threats
• Vulnerabilities
• And more...

Select the module you want to customize from this dropdown.

---

Form Builder Interface

Main Components

The Form Builder interface consists of several key areas:

┌─────────────────────────────────────────────────────────┐
│  [Module Selector ▼]  [Export] [Import] [Factory Reset] │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Module Display Settings                                │
│  ┌────────────────────────────────────────────────┐    │
│  │ Display Name: [Vulnerability              ]    │    │
│  │ Plural Name:  [Vulnerabilities            ]    │    │
│  │ Tab Sort:     [⚪ Alphabetical ⚫ Manual   ]    │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  Form Sections (Tabs)                                   │
│  ┌────────────────────────────────────────────────┐    │
│  │ ☰ Data Entry              [Edit] [Delete] [+]  │    │
│  │   ┌──────────────────────────────────────┐    │    │
│  │   │ ☰ Title              [Required] [✓]  │    │    │
│  │   │ ☰ Status             [Required] [✓]  │    │    │
│  │   │ ☰ Description        [      ]  [✓]  │    │    │
│  │   └──────────────────────────────────────┘    │    │
│  │                                                 │    │
│  │ ☰ Subsystems             [Edit] [Delete] [+]  │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  Rules                                                   │
│  ┌────────────────────────────────────────────────┐    │
│  │ [+ Add Rule]                                    │    │
│  │ Rule: Show CVE Fields                          │    │
│  │   Conditions: Status = "Open" AND ...          │    │
│  │   Actions: Show field "CVE Number"            │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  [Cancel]                              [Save Changes]   │
└─────────────────────────────────────────────────────────┘

Toolbar Actions

• Export: Download the current module configuration as a JSON file
• Import: Upload a previously exported configuration
• Factory Reset: Restore the module to its default RegScale configuration

Save Button

The Save Changes button at the bottom will:

• Save all your modifications to the database
• Update the form configuration for all users
• Display a success message when complete

Important: Always save your changes before navigating away or switching modules.

---

Managing Form Sections (Tabs)

Form sections (also called "tabs") organize fields into logical groups. For example, a vulnerability form might have sections for "Data Entry", "Subsystems", "Workflow", etc.

Viewing Sections

All sections for the selected module are displayed as expandable panels. Click on a section to expand and view its fields.

Adding a New Section

1. Click the [+ Add Section] button at the top of the sections area
2. A new section will appear with default settings
3. Click Edit on the new section to configure it:
   • Display Name: The label users will see (e.g., "Custom Fields")
   • Active: Toggle whether this section is visible to users
   • Default: Check if this should be the initially selected tab when opening a form

Editing a Section

1. Click the [Edit] button on the section header
2. Modify the section properties:
   • Display Name: Change the section label
   • Active: Enable/disable the section
   • Default: Set as the default tab
3. Click Save to apply changes

Reordering Sections

Drag-and-Drop Method:

1. Click and hold the ☰ (hamburger) icon on the left of a section name
2. Drag the section up or down to the desired position
3. Release to drop it in the new position
4. The order is saved when you click Save Changes

Manual Sort Option:

• At the module level, you can choose between:
  • Alphabetical: Sections are automatically sorted alphabetically by name
  • Manual: You control the order via drag-and-drop

Deleting a Section

Custom Sections:

1. Click the [Delete] button on the section
2. Confirm the deletion
3. All fields in that section will also be deleted

System Sections:

• Cannot be deleted
• Can be deactivated by editing and unchecking "Active"

---

Managing Form Fields

Fields are the individual input elements within each section (text boxes, dropdowns, checkboxes, etc.).

Viewing Fields

Expand a section to view all fields within it. Each field displays:

• ☰ Drag handle for reordering
• Field Name: The display label
• [Required]: Badge if field is required
• [✓]: Active status indicator
• [Edit] and [Delete] buttons

Adding a New Field

1. Expand the section where you want to add a field
2. Click the [+ Add Field] button within that section
3. A new field will appear at the bottom of the field list
4. Click [Edit] to configure the field (see Field Properties below)

Field Properties

When editing a field, you can configure:

Basic Properties

• Display Name: The label shown to users (e.g., "CVE Number")
• System Name: Internal database field name (e.g., "cveNumber")
  • Required for system fields
  • Optional for custom fields
  • Use camelCase with no spaces

Field Behavior

• Field Type: Select from 30+ available types (see Field Types Reference)
• Required: Check to make this a mandatory field
• Active: Uncheck to hide this field from users
• Editable: Uncheck to make this field read-only

Advanced Properties (depends on field type)

• Pattern: Validation regex pattern (for text fields)
• Min/Max: Numeric range limits (for number fields)
• Select Type: Data source for dropdown fields (users, organizations, etc.)

Editing a Field

1. Click the [Edit] button next to the field
2. Modify the field properties as needed
3. Click Save to apply changes

Important Notes:

• System fields (provided by RegScale) have certain restrictions
• Some properties may be locked for system fields
• Changing field type will reset type-specific properties

Reordering Fields

Within a Section:

1. Click and hold the ☰ icon on the left of a field
2. Drag up or down to reorder within the same section
3. Release to drop in the new position

Moving Between Sections:

1. Edit the field
2. Change the "Form Tab" dropdown to select a different section
3. Save the field
4. The field will move to the selected section

Duplicating a Field

1. Click the [Duplicate] button on the field (if available)
2. A copy of the field will be created with "(Copy)" appended to the name
3. Edit the duplicate to customize it

Deleting a Field

Custom Fields:

1. Click the [Delete] button
2. Confirm the deletion
3. The field will be removed from the form

System Fields:

• Cannot be deleted permanently
• Can be deactivated by editing and unchecking "Active"
• Deactivated fields are hidden from users but preserved in the database

---

Field Types Reference

RegScale supports over 30 field types to accommodate various data entry needs:

Text Input Types

Field Type	Description	Example Use
Text Field	Single-line text input	Names, titles, short descriptions
Text Area	Multi-line text input	Long descriptions, notes
Rich Text	HTML editor with formatting	Formatted descriptions, documentation
Email	Email address with validation	Contact emails
Phone	Phone number with validation	Contact numbers
URL	Web address with validation	External references, links
IP Address	IP address format validation	Network addresses
MAC Address	MAC address format validation	Hardware identifiers

Numeric Types

Field Type	Description	Example Use
Number	Decimal numbers	Scores, measurements
Whole Number	Integers only	Counts, quantities
Dollar	Currency with $ symbol	Costs, budgets
Currency Label	Read-only currency display	Calculated costs
Range	Numeric range slider	Priority levels

Date/Time Types

Field Type	Description	Example Use
Date	Date picker	Due dates, milestones
Date Time Hour	Date and time picker	Scheduled times, timestamps
Date Label	Read-only date display	Created dates

Selection Types

Field Type	Description	Example Use
Select	Dropdown with custom options	Status, category, type
Users	User selection dropdown	Assigned to, reviewers
Organizations	Organization picker	Responsible org
Facilities	Facility picker	Physical location
Risk Probability	Risk matrix probability	Risk assessment
Risk Consequence	Risk matrix consequence	Impact assessment
Compliance Settings	Compliance framework picker	Associated framework

Boolean Types

Field Type	Description	Example Use
Checkbox	Single checkbox	Flags, yes/no questions
Toggle	On/off switch	Enable/disable options

Special Types

Field Type	Description	Example Use
Label	Static text label	Instructions, headers
HTML	Custom HTML content	Rich formatted instructions
Section Header	Visual section divider	Grouping within a tab
Button	Clickable button	Custom actions

Selecting the Right Field Type

For Short Text: Use Text Field
For Long Text: Use Text Area or Rich Text
For Predefined Options: Use Select (dropdown)
For Yes/No Questions: Use Checkbox or Toggle
For Numbers: Use Number or Whole Number
For Money: Use Dollar
For Dates: Use Date or Date Time Hour
For User Assignment: Use Users

---

Dropdown Field Choices

When you create a field with type Select, you need to define the dropdown options (choices).

Managing Choices

After creating a Select field:

1. Edit the field
2. Scroll to the Choices section
3. You'll see a list of current choices

Adding a Choice

1. Click [+ Add Choice] in the Choices section
2. A new choice row will appear
3. Configure the choice:
   • Label: What users see in the dropdown
   • Value: The actual value stored in the database (often same as label)
   • Active: Whether this choice is available

Example

For a "Priority" dropdown:

• Label: "High", Value: "High", Active: ✓
• Label: "Medium", Value: "Medium", Active: ✓
• Label: "Low", Value: "Low", Active: ✓

Reordering Choices

1. Use the ☰ drag handle on each choice
2. Drag up or down to change the display order
3. The order affects how choices appear in the dropdown

Editing a Choice

1. Click the [Edit] button on the choice
2. Modify the Label, Value, or Active status
3. Save changes

Deleting a Choice

Custom Choices:

• Click [Delete] to permanently remove

System Choices:

• Cannot be deleted
• Deactivate instead by unchecking "Active"

Select Type vs. Custom Choices

Some Select fields use Select Type instead of custom choices:

• users: Automatically populated with system users
• orgs: Populated with organizations
• facilities: Populated with facilities
• probability/consequence: From risk matrix
• complianceSetting: From compliance frameworks

If you set a Select Type, you cannot add custom choices—the system manages the options.

---

Field Validations

Field validations allow you to enforce data quality rules beyond simple "required" checking.

Types of Validation

Validations can check if a field value:

• Equals a specific value
• Does not equal a value
• Is greater than or less than a number or date
• Is before or after a date
• Is within the last/next X days
• Has a value or is empty

Adding a Validation

1. Edit a field
2. Scroll to the Validations section
3. Click [+ Add Validation]
4. Configure the validation:
   • Operator: Select comparison type (EQUALS, GREATER_THAN, etc.)
   • Value Source: Choose between:
     • Constant: Enter a fixed value
     • Field Reference: Compare to another field's value
   • Value: Enter the comparison value or select a field
   • Error Message: (Optional) Custom message shown when validation fails

Validation Operators

Operator	Description	Example
EQUALS	Must equal value	Status EQUALS "Closed"
NOT_EQUALS	Must not equal value	Priority NOT_EQUALS "Low"
HAS_VALUE	Field must be filled	Description HAS_VALUE
NO_VALUE	Field must be empty	Mitigation NO_VALUE (for new records)
GREATER_THAN	Number/date greater than	Score GREATER_THAN 7
LESS_THAN	Number/date less than	Cost LESS_THAN 10000
BEFORE	Date before specified date	DueDate BEFORE "2024-12-31"
AFTER	Date after specified date	StartDate AFTER TODAY
WITHIN_LAST	Date within last X days	LastReview WITHIN_LAST 30
WITHIN_NEXT	Date within next X days	DueDate WITHIN_NEXT 7

Example Validations

Ensure CVE Number is filled for critical vulnerabilities:

• Field: CVE Number
• Operator: HAS_VALUE
• Condition: When Severity = "Critical"
• (This would actually be done via a Rule, see Rules Builder section)

Due Date must be in the future:

• Field: Due Date
• Operator: AFTER
• Value: TODAY

Score must be between 0 and 10:

• Add two validations on the Score field:
  • Validation 1: Score GREATER_THAN -1
  • Validation 2: Score LESS_THAN 11

Field-to-Field Validation

You can compare one field to another:

Start Date must be before End Date:

• Field: Start Date
• Operator: BEFORE
• Value Source: Field Reference
• Field Reference: End Date

Removing a Validation

1. Click [Delete] next to the validation
2. Confirm removal
3. Save the field

---

Rules Builder

The Rules Builder is the most powerful feature of the Form Builder, allowing you to create conditional logic that dynamically changes form behavior based on user input or system state.

What Are Rules?

Rules consist of:

1. Conditions: What must be true for the rule to activate
2. Actions: What happens when conditions are met
3. Conditional Logic: How multiple conditions are combined (AND/OR)

Rule Structure

IF [Conditions are met]
THEN [Perform actions]

Example:
IF Status = "Closed" AND Severity = "Critical"
THEN Require field "Closure Notes" AND Show field "Remediation Date"

Accessing the Rules Builder

1. In the Form Builder, scroll to the Rules section at the bottom
2. You'll see a list of existing rules for the module
3. Click [+ Add Rule] to create a new rule

---

Creating a Rule

Step 1: Add a Rule

1. Click [+ Add Rule]
2. A new rule panel will appear
3. Give it a descriptive name (e.g., "Show CVE fields for critical vulnerabilities")

Step 2: Set Conditional Logic

Choose how multiple conditions should be evaluated:

• AND: All conditions must be true
• OR: At least one condition must be true

Step 3: Add Conditions

Conditions determine when the rule activates.

1. Click [+ Add Condition]

2. Select Condition Type:

   • Field: Check the value of a form field
   • System - No Parent: True when creating a new record (no parent entity)
   • System - No Condition: Always true (use for rules that always apply)
   • Tenant Feature: Check if a tenant feature is enabled
   • Module: Check if a module is enabled

3. For Field conditions, configure:

   • Field: Select which field to check
   • Operator: How to compare (EQUALS, GREATER_THAN, etc.)
   • Value: What to compare against

4. Click Save

Step 4: Add Actions

Actions define what happens when conditions are met.

1. Click [+ Add Action]

2. Select Action Type:

   • SHOW: Make a field or tab visible
   • HIDE: Hide a field or tab
   • REQUIRE: Make a field mandatory
   • NOT_REQUIRE: Make a field optional
   • ENABLE: Make a field editable
   • DISABLE: Make a field read-only
   • SET_VALUE: Automatically populate a field value
   • VALIDATE: Apply validation to a field

3. Select the Target: Which field or tab to affect

4. For SET_VALUE and VALIDATE actions:

   • Operator: How to set/validate the value
   • Value: The value to set or validate against
   • Bypass Existing Value: Whether to overwrite existing data
   • Allow External Value: Whether external systems can override

5. Click Save

Step 5: Save the Rule

After adding conditions and actions, click Save Changes at the bottom of the Form Builder.

---

Rule Examples

Example 1: Show Additional Fields for High Severity

Use Case: When a vulnerability is marked as "Critical" or "High" severity, require additional documentation.

Configuration:

• Rule Name: "High Severity Requirements"
• Conditional Logic: OR
• Conditions:
  • Condition 1: Severity EQUALS "Critical"
  • Condition 2: Severity EQUALS "High"
• Actions:
  • Action 1: REQUIRE field "Mitigation Plan"
  • Action 2: SHOW field "Estimated Remediation Date"
  • Action 3: REQUIRE field "Business Impact"

Example 2: Auto-populate Field Based on Status

Use Case: When status changes to "Closed", automatically set the "Closed Date" to today.

Configuration:

• Rule Name: "Set Closed Date"
• Conditional Logic: AND
• Conditions:
  • Condition 1: Status EQUALS "Closed"
• Actions:
  • Action 1: SET_VALUE on "Closed Date" with value "TODAY"

Example 3: Hide Irrelevant Fields for New Records

Use Case: On new vulnerability records, hide the "Resolution" section until the vulnerability is being remediated.

Configuration:

• Rule Name: "Hide Resolution for New Records"
• Conditional Logic: AND
• Conditions:
  • Condition 1: System - NO_PARENT (new record)
• Actions:
  • Action 1: HIDE tab "Resolution"

Example 4: Enable Feature-Based Fields

Use Case: Only show advanced AI fields if the tenant has the AI feature enabled.

Configuration:

• Rule Name: "Show AI Fields"
• Conditional Logic: AND
• Conditions:
  • Condition 1: Tenant Feature - "AI Tools" ENABLED
• Actions:
  • Action 1: SHOW field "AI Risk Score"
  • Action 2: SHOW field "AI Recommendations"

Example 5: Cross-Field Validation

Use Case: If "External Vendor" checkbox is checked, require "Vendor Name" to be filled.

Configuration:

• Rule Name: "Require Vendor Name"
• Conditional Logic: AND
• Conditions:
  • Condition 1: External Vendor EQUALS "true"
• Actions:
  • Action 1: REQUIRE field "Vendor Name"
  • Action 2: SHOW field "Vendor Contact"

Example 6: Multiple Condition AND Logic

Use Case: Only show "Regulatory Reporting" section if both: (1) Severity is Critical AND (2) Compliance framework is enabled.

Configuration:

• Rule Name: "Show Regulatory Reporting"
• Conditional Logic: AND
• Conditions:
  • Condition 1: Severity EQUALS "Critical"
  • Condition 2: Module - "Compliance" ENABLED
• Actions:
  • Action 1: SHOW tab "Regulatory Reporting"

---

Managing Rules

Editing a Rule

1. Click [Edit] on the rule panel
2. Modify conditions, actions, or logic
3. Save changes

Duplicating a Rule

1. Click [Duplicate] on the rule
2. A copy will be created with "(Copy)" in the name
3. Edit the duplicate as needed

Deleting a Rule

1. Click [Delete] on the rule
2. Confirm deletion
3. Note: System-required rules cannot be deleted

Disabling a Rule

If you can't delete a rule but want to temporarily disable it, you can:

• Remove all actions (rule won't do anything)
• Or use a condition that's never true (e.g., NO_CONDITION then negate it)

---

Condition Types Reference

Field Conditions

Check the value of any field in the form.

Available Operators (depends on field type):

• Text Fields: EQUALS, NOT_EQUALS, HAS_VALUE, NO_VALUE
• Number Fields: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, HAS_VALUE, NO_VALUE
• Date Fields: EQUALS, NOT_EQUALS, BEFORE, AFTER, WITHIN_LAST, WITHIN_NEXT, HAS_VALUE, NO_VALUE
• Dropdown Fields: EQUALS, NOT_EQUALS, HAS_VALUE, NO_VALUE
• Checkbox/Toggle: EQUALS (true/false), HAS_VALUE, NO_VALUE

System Conditions

NO_PARENT:

• True when creating a new record (no parent entity linked)
• Useful for showing/hiding fields on new vs. existing records

NO_CONDITION:

• Always evaluates to true
• Use for rules that should always apply
• Useful when you want actions to execute unconditionally

Tenant Feature Conditions

Check if a specific RegScale feature is enabled for your tenant.

Operator: ENABLED, DISABLED

Example Features:

• AI Tools
• Advanced Reporting
• Custom Integrations
• (Check with your administrator for available features)

Module Conditions

Check if a specific RegScale module is enabled.

Operator: ENABLED, DISABLED

Example Modules:

• Vulnerabilities
• Risks
• Issues
• Compliance
• Assets
• (All RegScale modules)

---

Action Types Reference

SHOW

Makes a field or tab visible to users.

Use Cases:

• Show optional fields based on selections
• Display additional sections when needed
• Reveal advanced options for power users

Configuration:

• Target: Select field or tab to show

HIDE

Hides a field or tab from users.

Use Cases:

• Hide irrelevant fields based on context
• Simplify forms for basic use cases
• Remove unused sections

Configuration:

• Target: Select field or tab to hide

REQUIRE

Makes a field mandatory (user must fill it in).

Use Cases:

• Enforce required documentation for critical items
• Ensure compliance with policies
• Require approvals for certain conditions

Configuration:

• Target: Select field to make required

NOT_REQUIRE

Makes a field optional (removes mandatory status).

Use Cases:

• Make fields conditionally optional
• Reduce burden for low-priority items
• Allow flexibility based on context

Configuration:

• Target: Select field to make optional

ENABLE

Makes a field editable by users.

Use Cases:

• Allow editing based on user role
• Enable fields when prerequisites are met
• Unlock fields after approval

Configuration:

• Target: Select field to enable

DISABLE

Makes a field read-only (users can see but not edit).

Use Cases:

• Lock fields after approval
• Prevent changes in certain states
• Display calculated or system-managed values

Configuration:

• Target: Select field to disable

SET_VALUE

Automatically populates a field with a specific value.

Use Cases:

• Auto-fill dates (e.g., set "Closed Date" when status = "Closed")
• Set default values based on conditions
• Copy values from other fields
• Calculate derived values

Configuration:

• Target: Select field to populate
• Operator: How to set the value (EQUALS, etc.)
• Value: The value to set (can be constant or reference another field)
• Bypass Existing Value: Check to overwrite even if field has data
• Allow External Value: Check to allow API/integrations to override

Special Values:

• TODAY: Current date
• NOW: Current date and time
• @FieldName: Reference another field's value

VALIDATE

Applies validation rules to a field based on conditions.

Use Cases:

• Enforce business rules (e.g., "Due Date must be within 30 days when Priority = High")
• Apply conditional constraints
• Validate cross-field relationships

Configuration:

• Target: Select field to validate
• Operator: Validation type (GREATER_THAN, BEFORE, etc.)
• Value: Validation constraint

---

Rule Execution Order

Rules are evaluated in the order they appear in the list. However:

• All conditions are evaluated first
• Then all actions are executed for rules with true conditions
• Multiple rules can affect the same field (last action wins in case of conflicts)

Best Practice: Order rules from most general to most specific, so specific rules can override general ones.

---

Rule Validation

The Form Builder validates rules before allowing you to save:

Rule Validation Checks:

• ✓ Rule has a name
• ✓ At least one condition exists
• ✓ At least one action exists
• ✓ All conditions reference valid fields
• ✓ All actions reference valid fields or tabs
• ✓ Operators are appropriate for field types
• ✓ Required values are provided

If validation fails, you'll see error messages indicating what needs to be fixed.

---

Import and Export

Import and Export allow you to back up configurations, migrate between environments, or share customizations.

Exporting a Module Configuration

1. Select the module you want to export
2. Click the [Export] button in the toolbar
3. A JSON file will be downloaded to your computer
   • File name format: moduleName-export-YYYY-MM-DD.json
4. Store this file safely as a backup

What's Included in Export:

• Module display settings
• All form sections (tabs)
• All form fields (system and custom)
• Field choices
• Field validations
• All rules with conditions and actions

What's NOT Included:

• Actual data records (vulnerabilities, risks, etc.)
• User-specific configurations
• Database IDs (these are regenerated on import)

Importing a Module Configuration

Prerequisites:

• You must have an exported JSON file
• You must be an Administrator
• The target module must exist in RegScale

Steps:

1. Select the module where you want to import
2. Click the [Import] button in the toolbar
3. Click Choose File and select your JSON export file
4. Click Import
5. The system will:
   • Validate the import file
   • Check for conflicts
   • Merge the configuration
6. Review the imported configuration
7. Click Save Changes to apply

Import Behavior:

• System fields: Updated with imported properties
• Custom fields: Added if they don't exist, updated if they match by name
• Sections: Merged with existing sections
• Rules: Imported rules are added (duplicates if same rule exists)
• Field IDs: Automatically remapped to match target environment

Validation During Import:
The system checks:

• All required system fields are present
• Field types are valid
• References between rules and fields are valid
• JSON structure is correct

If validation fails, the import is rejected with error messages.

Use Cases for Import/Export

Use Case 1: Environment Migration

Export from Development → Import to Production to deploy form customizations.

Use Case 2: Backup Before Changes

Export before making major changes, so you can restore if needed.

Use Case 3: Sharing Between Tenants

Export from one tenant, import to another to share best practices.

Use Case 4: Template Library

Create standardized form configurations for specific industries or compliance frameworks.

---

Factory Reset

Factory Reset restores a module's form configuration to the default RegScale settings.

When to Use Factory Reset

• You've made extensive changes and want to start over
• Forms are behaving unexpectedly due to complex rules
• You want to revert to the standard RegScale form
• After testing custom configurations, you want to return to baseline

What Factory Reset Does

Resets:

• All system field properties (required, active, sequence, etc.)
• Form section names and order
• System rules

Preserves:

• All custom fields you've added (marked inactive but not deleted)
• Actual data records in the database

Performing a Factory Reset

1. Select the module to reset
2. Click [Factory Reset] in the toolbar
3. A confirmation dialog will appear
4. Type "RESET" in the confirmation box (case-sensitive)
5. Click Confirm Reset
6. The form will reload with default configuration
7. Review the reset configuration
8. Custom fields will be preserved but marked as inactive

Warning: This action cannot be undone. Always export a backup before performing a factory reset.

After Factory Reset

1. Review the default configuration
2. Identify which custom fields you want to reactivate
3. Edit those fields and check "Active"
4. Save changes
5. Recreate any custom rules you need

---

Common Use Cases

Use Case 1: Adding a Custom Field to Vulnerabilities

Scenario: Your organization needs to track "Business Owner" for each vulnerability.

Steps:

1. Go to Admin → Form Builder
2. Select "Vulnerabilities" module
3. Expand the "Data Entry" section
4. Click [+ Add Field]
5. Configure the field:
   • Display Name: "Business Owner"
   • System Name: "businessOwner"
   • Field Type: "Users" (to select from user list)
   • Required: Check if mandatory
   • Active: Checked
6. Click Save on the field
7. Click Save Changes at the bottom
8. The new field now appears on all vulnerability forms

---

Use Case 2: Creating a Conditional Approval Section

Scenario: For high-value risks (over $100,000), require executive approval fields.

Steps:

1. Select "Risks" module
2. Add a new section called "Executive Approval"
3. Add fields to this section:
   • "Executive Approver" (Users field)
   • "Approval Date" (Date field)
   • "Approval Notes" (Text Area)
4. Create a rule:
   • Rule Name: "Require Executive Approval"
   • Condition: Financial Impact GREATER_THAN 100000
   • Actions:
     • SHOW tab "Executive Approval"
     • REQUIRE field "Executive Approver"
     • REQUIRE field "Approval Date"
5. Save changes
6. Now the Executive Approval section only appears when Financial Impact > $100,000

---

Use Case 3: Auto-populate Dates Based on Status

Scenario: Automatically set "Resolved Date" when issue status changes to "Resolved".

Steps:

1. Select "Issues" module
2. Ensure "Resolved Date" field exists (add if needed)
3. Create a rule:
   • Rule Name: "Set Resolved Date"
   • Condition: Status EQUALS "Resolved"
   • Actions:
     • SET_VALUE on "Resolved Date" with value "TODAY"
     • Bypass Existing Value: Unchecked (don't overwrite if already set)
4. Save changes
5. Now when an issue is marked "Resolved", the date is auto-filled

---

Use Case 4: Simplify Forms for New Records

Scenario: Hide advanced fields when creating a new record, show them only after initial save.

Steps:

1. Select your module
2. Create a new section called "Advanced Options"
3. Move advanced fields into this section
4. Create a rule:
   • Rule Name: "Hide Advanced for New Records"
   • Condition: System - NO_PARENT
   • Actions:
     • HIDE tab "Advanced Options"
5. Save changes
6. The Advanced Options tab is hidden when creating new records, visible when editing existing ones

---

Use Case 5: Compliance-Specific Fields

Scenario: Show HIPAA-specific fields only when HIPAA compliance framework is selected.

Steps:

1. Select "Security Controls" module
2. Add custom fields for HIPAA requirements in a section
3. Create a rule:
   • Rule Name: "Show HIPAA Fields"
   • Condition: Compliance Framework EQUALS "HIPAA"
   • Actions:
     • SHOW field "HIPAA Safeguard Type"
     • SHOW field "PHI Impact"
     • REQUIRE field "HIPAA Safeguard Type"
4. Save changes
5. HIPAA fields appear only when the HIPAA framework is selected

---

Use Case 6: Cross-Field Validation

Scenario: Ensure "End Date" is after "Start Date" for tasks.

Steps:

1. Select "Tasks" module
2. Edit the "End Date" field
3. Add a validation:
   • Operator: AFTER
   • Value Source: Field Reference
   • Field: "Start Date"
   • Error Message: "End Date must be after Start Date"
4. Save the field
5. Save changes
6. Users will receive an error if they set End Date before Start Date

---

Use Case 7: Feature-Based Field Visibility

Scenario: Show AI-generated recommendations only if the AI feature is enabled for the tenant.

Steps:

1. Select your module
2. Add a field "AI Recommendations" (Text Area)
3. Create a rule:
   • Rule Name: "Show AI Features"
   • Condition: Tenant Feature - "AI Tools" ENABLED
   • Actions:
     • SHOW field "AI Recommendations"
     • ENABLE field "AI Recommendations"
4. Save changes
5. AI field appears only for tenants with the AI feature enabled

---

Best Practices

Planning

1. Document Your Requirements: Before making changes, write down what fields you need and why
2. Start Small: Add a few fields at a time, test, then add more
3. Test in Development: If possible, test configurations in a development environment first
4. Export Before Major Changes: Always export a backup before significant modifications

Field Design

1. Use Descriptive Names: Field names should be clear and unambiguous

   • Good: "Executive Approver", "Remediation Due Date"
   • Bad: "Approver", "Date1"

2. Consistent Naming: Follow a naming convention

   • Use same terminology across modules
   • Be consistent with capitalization

3. System Names: Use camelCase with no spaces

   • Good: "businessOwner", "remediationDate"
   • Bad: "Business Owner", "remediation-date"

4. Required Fields: Only mark truly mandatory fields as required

   • Too many required fields frustrate users
   • Use conditional requirements (via rules) when possible

5. Field Types: Choose the most specific type

   • Use "Email" not "Text Field" for emails
   • Use "Number" not "Text Field" for numeric data
   • Use proper types for better validation and reporting

Section Organization

1. Logical Grouping: Group related fields together

   • Example: All approval fields in "Approval" section

2. Commonly Used First: Place frequently used fields in the default tab

3. Advanced Features Last: Put power-user fields in separate sections

4. Limit Sections: Don't create too many tabs (5-7 is usually sufficient)

Rules Best Practices

1. Clear Rule Names: Names should describe what the rule does

   • Good: "Show CVE Fields for Critical Vulnerabilities"
   • Bad: "Rule 1"

2. Single Purpose: Each rule should do one logical thing

   • Don't combine unrelated actions in one rule
   • Better to have multiple simple rules than one complex rule

3. Test Thoroughly: Test rules with different scenarios

   • Test with empty fields
   • Test with different field values
   • Test rule combinations

4. Avoid Conflicts: Be careful when multiple rules affect the same field

   • Last rule wins in case of conflicts
   • Consider using OR logic within a rule instead of multiple rules

5. Document Complex Rules: Add comments in rule names or keep external documentation

6. Use System Conditions Wisely:

   • NO_PARENT for new record behavior
   • NO_CONDITION for always-active rules
   • Combine with other conditions for fine control

Performance Considerations

1. Minimize Rules: More rules = slower form rendering

   • Combine similar conditions where possible
   • Remove unused rules

2. Avoid Circular Dependencies: Don't create rules that trigger each other

   • Rule A sets Field X based on Field Y
   • Rule B sets Field Y based on Field X
   • This causes infinite loops

3. Limit Dropdown Choices: Very large dropdown lists slow performance

   • If you have 100+ choices, consider a different approach
   • Use type-ahead or search functionality instead

Maintenance

1. Regular Reviews: Periodically review your form configurations

   • Remove unused fields
   • Clean up obsolete rules
   • Simplify where possible

2. Version Control: Keep a library of exported configurations

   • Export after each major change
   • Name exports with date and description
   • Store in a secure location

3. Documentation: Maintain documentation of:

   • What custom fields mean
   • Why specific rules were created
   • Business logic behind validations

4. Communication: Inform users about form changes

   • Notify before major changes
   • Provide training for new fields
   • Document new requirements

---

Troubleshooting

Issue: Changes Not Appearing

Problem: I saved changes but they don't appear in forms.

Solutions:

1. Hard Refresh: Clear browser cache or do a hard refresh (Ctrl+F5)
2. Check Active Status: Ensure the field/section is marked as "Active"
3. Verify Save: Check for error messages during save
4. Rule Hiding Field: A rule might be hiding the field—review rules
5. Wrong Module: Ensure you edited the correct module

---

Issue: Validation Errors Preventing Save

Problem: Cannot save due to validation errors.

Solutions:

1. Read Error Messages: Scroll through to find all error indicators (usually highlighted in red)
2. Common Issues:
   • Empty field names
   • Duplicate field names
   • Missing field types
   • Rules with no conditions or actions
   • Invalid rule references (deleted fields)
3. Fix Systematically: Address each error one at a time
4. Delete Problem Rules: If a rule is causing issues, delete and recreate it

---

Issue: Rule Not Working

Problem: Created a rule but it doesn't execute.

Solutions:

1. Check Conditions:

   • Are conditions true? Test with sample data
   • Is conditional logic correct (AND vs. OR)?
   • Are field names correct in conditions?

2. Check Actions:

   • Are target fields correct?
   • Are actions appropriate for field types?
   • Are there conflicting rules?

3. Check Rule Order: Rules are evaluated in order—later rules can override earlier ones

4. System vs. Custom Fields: Some system fields may not be affected by certain rule actions

5. Test Incrementally:

   • Create a simple rule with one condition and one action
   • Verify it works
   • Add complexity gradually

---

Issue: Field Not Showing in Dropdown

Problem: Can't find a field in the rule builder dropdown.

Solutions:

1. Check Field Tab: Field must be in the correct section
2. Field Active Status: Field must be marked as "Active"
3. Field Type Compatibility: Some field types can't be used in certain rule contexts
4. Refresh: Save and reload the Form Builder to refresh dropdowns

---

Issue: Import Failed

Problem: Import operation failed with errors.

Solutions:

1. Check JSON Format: Ensure the file is valid JSON
2. Correct Module: Ensure you're importing to the correct module
3. Version Compatibility: Export may be from a different RegScale version
4. Validation Errors: Read error messages—may indicate missing required fields
5. Try Manual Recreation: If import fails repeatedly, manually recreate the configuration

---

Issue: Lost Customizations

Problem: Customizations disappeared or were reset.

Solutions:

1. Check Export Backups: Restore from most recent export
2. Check Inactive Fields: Fields may be deactivated rather than deleted
3. Factory Reset Accident: If factory reset was performed, custom fields are preserved but inactive—reactivate them
4. Contact Support: If data is truly lost, contact RegScale support immediately

---

Issue: Duplicate Field Names

Problem: System won't save due to duplicate field names.

Solutions:

1. Find Duplicates: Scroll through all sections to find fields with same display name
2. Rename: Make names unique (e.g., "Description" → "Vulnerability Description")
3. System vs. Custom: System field names cannot be changed—rename custom field instead
4. Different Sections: Even in different sections, names must be unique within the module

---

Issue: Cannot Delete Field

Problem: Delete button doesn't work or field comes back after deletion.

Solutions:

1. System Field: Cannot delete system fields—mark as inactive instead
2. Rule References: Delete any rules referencing this field first
3. Validation References: Remove validations on other fields that reference this field
4. Save After Delete: Must click "Save Changes" after deleting

---

Issue: Slow Form Loading

Problem: Forms load very slowly after customization.

Solutions:

1. Reduce Rules: Each rule adds processing time—remove unused rules
2. Simplify Conditions: Complex nested conditions slow evaluation
3. Large Choice Lists: Dropdowns with 100+ choices slow rendering—consider alternative approach
4. Too Many Fields: Excessive fields on one section slow rendering—split into multiple sections
5. Browser Cache: Clear browser cache and cookies

---

Issue: Field Value Not Setting

Problem: SET_VALUE action in rule doesn't populate the field.

Solutions:

1. Check Bypass Setting: "Bypass Existing Value" must be checked to overwrite existing data
2. Field Type Mismatch: Ensure value type matches field type (date for date fields, etc.)
3. Read-Only Field: Field might be disabled—can't set value on disabled fields
4. Format: Ensure value format is correct (dates as YYYY-MM-DD, etc.)
5. Special Keywords: Use "TODAY" or "NOW" for current date/time, not literal strings

---

Issue: Users See Different Forms

Problem: Different users see different fields or layouts.

Solutions:

1. Tenant Isolation: Each tenant has separate form configurations—verify you're comparing same tenant
2. Role-Based Rules: Rules might show/hide fields based on user properties
3. Feature Flags: Tenant features might enable/disable certain sections
4. Browser Cache: Users may have cached old form version—instruct them to hard refresh
5. Module Context: Ensure comparing same module (Vulnerabilities vs. Risks, etc.)

---

Issue: Cannot Create Rule

Problem: Add Rule button doesn't work or rule doesn't save.

Solutions:

1. Maximum Rules: Check if there's a limit on number of rules (unlikely)
2. Validation: Rule might have validation errors preventing save
3. Browser Issues: Try different browser or clear cache
4. Permissions: Ensure you have Administrator role
5. Module Locked: Some system modules might have restrictions

---

Getting Help

If you encounter issues not covered in this guide:

1. Export Configuration: Export the problematic module as a backup
2. Document the Issue:
   • What you were trying to do
   • Steps you took
   • Error messages received
   • Screenshots if applicable
3. Contact Support: Reach out to RegScale support with documentation
4. Community Forums: Check RegScale community forums for similar issues
5. Training Resources: Review RegScale training materials and videos

---

Appendix: Keyboard Shortcuts

While using the Form Builder:

• Ctrl+S: Save changes (if browser allows)
• Ctrl+F: Find on page (locate specific fields)
• Esc: Close modal dialogs
• Tab: Navigate between form inputs
• Enter: Submit/Save in modal dialogs

---

Appendix: Data Model Reference

Understanding the underlying data structure can help with advanced configurations:

Module Structure

• Module: Top-level container (Vulnerabilities, Risks, etc.)
  • Form Tabs: Sections within the module
    • Form Fields: Individual input fields
      • Choices: Dropdown options (for Select fields)
      • Validations: Field validation rules
  • Rules: Conditional logic
    • Conditions: When to activate rule
    • Actions: What to do when activated

Field Identifiers

Each field has multiple identifiers:

• ID: Database primary key (auto-generated)
• Display Name: User-visible label
• System Name (regScaleName): Internal database column name
• System ID (regScaleId): Unique identifier for system fields

Custom fields may not have System Name/ID set.

Rule Identifiers

Rules use:

• ID: Database primary key
• UUID: Universally unique identifier (for client-side tracking)
• Rule Name: User-visible name

---

Appendix: Advanced Topics

Custom Field Patterns

Pattern Validation:
Fields support regex patterns for validation. Common patterns:

• Email: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
• Phone: ^\+?1?\d{9,15}$
• URL: ^https?://.*
• IP Address: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$
• Alphanumeric: ^[a-zA-Z0-9]+$
• Numbers Only: ^\d+$

Field References in Rules

When using SET_VALUE actions, you can reference other fields:

• Use @FieldSystemName to reference another field's value
• Example: @startDate references the Start Date field

Date/Time Special Values

In SET_VALUE actions:

• TODAY: Current date (midnight)
• NOW: Current date and time
• TOMORROW: Tomorrow's date
• YESTERDAY: Yesterday's date

Calculated Fields

While not directly supported, you can approximate calculated fields using:

1. Create a read-only field
2. Create a rule with SET_VALUE action
3. Use field references in the value
4. Set "Allow External Value" to let backend recalculate

---

Conclusion

The Form Builder and Rules Builder provide powerful capabilities for customizing RegScale forms to match your organization's unique needs. By following the practices in this guide, you can:

• Create intuitive, user-friendly forms
• Enforce business rules and compliance requirements
• Automate repetitive data entry tasks
• Maintain data quality through validation
• Adapt RegScale to your specific workflows

Remember to:

• ✅ Plan changes before implementing
• ✅ Test thoroughly in a development environment
• ✅ Export backups before major changes
• ✅ Document custom configurations
• ✅ Train users on new fields and workflows
• ✅ Review and optimize regularly

For additional assistance, contact RegScale support or consult the RegScale community forums.

---

Document Version: 1.0
Last Updated: 2024
Applies to: RegScale Platform with Form Builder feature