Skip to main content

Optional Steps (To be removed)

Description​

The Optional Steps screen allows users to dynamically show or hide certain scan flow steps or zone linking steps during the scanning process. Optional steps are fields that can be toggled on or off based on user preference, providing flexibility in data collection. This feature is accessible from both the Add Scans screen and the Zone Linking screen when optional fields are available after the currently selected step.

What Are Optional Fields​

Definition​

Optional fields are scan flow steps or zone linking steps that have a specific visibility rule configuration:

  • The step has a visibilityRules list containing at least one rule.
  • One of those rules has keyCode = 1 (a special key code designating it as optional).

Identifying Optional Steps​

The getOptionals() function filters steps to find optional ones:

fun List<Step>.getOptionals() = this.filter {
    it.visibilityRules?.any { rule -> rule.keyCode == 1 } == true
}

Key Points:

  • Only steps with keyCode = 1 in their visibility rules are considered optional.
  • This key code is a marker that indicates "this step can be toggled by the user."
  • Not all steps with visibility rules are optional - only those with this specific key code.

Why Optional Fields Exist​

Optional fields provide flexibility in data collection:

  • Core Fields: Always required and visible (e.g., Barcode, Count).
  • Optional Fields: Additional data that may be relevant for some items but not others (e.g., Color, Size, Condition, Notes).
  • Users can enable optional fields when needed and hide them to speed up scanning when not needed.

How Optional Fields Are Defined​

Step Configuration​

Each optional step must have:

  1. Visibility Rules: A list of FieldRuleDomainEntity objects.
  2. Key Code = 1: At least one visibility rule with keyCode = 1.
  3. Display Name: A user-friendly label shown in the optional fields list.
  4. Order: Determines the step's position in the scan flow sequence.
  5. Value DB Field Name: The database field this step populates.

Example Configuration​

Step: "Item Color"
  - valueDBFieldName: "Color"
  - displayName: "Item Color"
  - order: 5
  - isVisible: false (initially hidden)
  - visibilityRules: [
      { keyCode: 1, operator: null, dbFieldName: null, regEx: null }
    ]

This step is optional because it has a visibility rule with keyCode = 1. Users can toggle it on/off.

Visibility Rules Structure​

FieldRuleDomainEntity contains:

  • keyCode: Integer identifying the rule type (1 = optional toggle).
  • operator: Comparison operator (not used for optional fields).
  • dbFieldName: Field to check against (not used for optional fields).
  • regEx: Pattern to match (not used for optional fields).

For optional fields, only keyCode = 1 is relevant. The other properties are used for conditional visibility rules.

When Optional Fields Are Available​

Availability Conditions​

Optional fields can be accessed when:

  1. The current flow (Scan or Zone Linking) has steps with optional configurations.
  2. At least one optional step exists after the currently selected step.
  3. The optional step has a different display name than the selected step.

hasOptionalFields() Logic​

fun List<FlowEntry>.hasOptionalFields() =
    this.any { step ->
        val selectedStep = this.selectedEntry()?.step ?: return false
        
        step.visibilityRules?.any { rule -> rule.keyCode == 1 } == true &&
        step.displayName != selectedStep.displayName &&
        step.order > selectedStep.order
    }

Conditions Explained:

  • Has keyCode = 1: Step is marked as optional.
  • Different display name: Can't toggle the currently selected step.
  • Order > selected order: Only shows future steps, not previous ones.

This ensures users can only toggle optional fields that come after their current position in the flow.

Optional Fields Screen Functionality​

GetOptionalSteps - Fetching Optional Steps​

When the screen loads:

  1. Determine Flow Type: Gets the action flow (Scan or Zone Linking) from saved state.
  2. Load Steps:
    • For Scan flow: Loads scan flow steps from configuration.
    • For Zone Linking: Loads zone linking steps from configuration.
  3. Filter Optional Steps: Applies getOptionals() to find steps with keyCode = 1.
  4. Sort and Filter:
    • Sorts by order (sequential position in flow).
    • Removes the currently selected step.
    • Removes steps that come before the currently selected step.
  5. Map to UI Model: Converts each step to OptionalField with:
    • Step ID
    • Display name
    • Current visibility status (isVisible)

Toggling Visibility​

When a user toggles an optional field:

  1. Update Local State: Flips the isVisible flag in the UI model.
  2. Show Change in Real-Time: List updates to reflect the toggle.
  3. No Database Update Yet: Changes are held in memory until saved.

Saving Changes - UpdateOptionalStepsVisibility​

When the user confirms their changes:

  1. Collect Updates: Creates a map of stepId -> isVisible for all fields.
  2. Determine Flow: Checks if it's Scan or Zone Linking mode.
  3. Update Database:
    • For Scan flow: Calls updateScanFlowStepVisibility() for each step.
    • For Zone Linking: Calls updateZoneLinkingStepVisibility() for each step.
  4. Persist Changes: Updates are saved to the configuration database.
  5. Navigate Back: Returns to the previous screen with updated step visibility.

ToggleOptionalStepVisibility - Single Toggle (Alternative)​

There's also a quick toggle function for changing one step at a time:

  1. Load Optional Steps: Gets all optional steps for the current flow.
  2. Find Target Step: Locates the specific step to toggle (matching criteria).
  3. Toggle Visibility: Flips isVisible to the opposite value.
  4. Update Database: Immediately saves the change to configuration.

This is used for quick single-step toggles without opening the full optional fields screen.

Usage in Scan Mode and Zone Linking​

In Add Scans Screen​

  • Button Available: When isSelectOptionalFieldsEnabled = true.
  • Keyboard Shortcut: F7 key opens the optional fields screen.
  • After Selection: Updated steps become visible/hidden in the scan flow.
  • Dynamic Flow: Users can add/remove steps mid-scanning session.

In Zone Linking Screen​

  • Same Behavior: Identical functionality as scan mode.
  • Zone Linking Steps: Toggles visibility of zone linking-specific fields.
  • Flow Adjustment: Helps customize zone linking data collection.

Complete Flow Example​

Scenario: Adding "Item Condition" Optional Field​

Initial State:

  • User is scanning items in Add Scans mode.
  • Currently on "Barcode" step (order 3).
  • "Item Condition" step (order 6) is optional and currently hidden.
  • "Item Condition" has visibilityRules = [{ keyCode: 1 }].

Flow:

  1. User presses F7 or clicks "Optional Fields" button.
  2. System calls GetOptionalSteps:
    • Loads all scan flow steps.
    • Filters to steps with keyCode = 1.
    • Filters to steps after "Barcode" (order > 3).
    • Returns: ["Item Condition" - currently hidden].
  3. Optional Fields screen displays: "Item Condition ☐ (unchecked)".
  4. User clicks the toggle.
  5. UI updates: "Item Condition ☑ (checked)".
  6. User clicks "Save Changes".
  7. System calls UpdateOptionalStepsVisibility:
    • Updates: { "condition-step-id": true }.
    • Calls updateScanFlowStepVisibility("condition-step-id", true).
  8. Screen navigates back to Add Scans.
  9. "Item Condition" step now appears in the scan flow after "Barcode".
  10. User can now enter item condition data during scanning.

Fields​

No input fields - this is a toggle list interface.

Error Messages​

No specific error messages documented for this screen.