Skip to main content
Version: 1.0

Formulus Features

Complete user guide for the Formulus mobile application.

Overview

The Formulus app is an offline-first mobile data collection tool that:

  • Works offline - Collect data without internet connection
  • Syncs when connected - Push data to server when online
  • Supports custom apps - Load custom forms and workflows
  • Captures rich data - Photos, GPS, signatures, audio, and more

Getting Started

Step 1: Install the App

The Formulus app should be installed on your Android device. If not already installed:

# From your development machine
cd formulus
npm run android

Or install the APK directly:

  • APK location: formulus/android/app/build/outputs/apk/debug/

Step 2: Configure the App

  1. Open Formulus app on your device
  2. Tap "Scan QR Code" on the welcome/settings screen
  3. Point camera at the QR code generated by CLI
  4. Settings auto-populate - Server URL, username, password
  5. Tap "Connect" to verify and save

Option B: Manual Configuration

  1. Open Formulus app
  2. Go to Settings (gear icon or menu)
  3. Enter Server URL: http://YOUR_SERVER_IP (e.g., http://192.168.100.7)
  4. Enter Username: Your username
  5. Enter Password: Your password
  6. Tap "Test Connection" to verify
  7. Tap "Save"

Step 3: Login

After configuration:

  1. Navigate to Login screen (if not automatic)
  2. Credentials should be pre-filled (from QR or manual entry)
  3. Tap "Login"
  4. Wait for authentication - Token is stored locally

Success indicators:

  • ✅ "Login successful" message
  • ✅ Redirected to home/dashboard
  • ✅ User info displayed

App Navigation

Main Screens

ScreenDescriptionAccess
Home/DashboardOverview and quick actionsDefault screen
FormsList of available formsBottom tab or menu
ObservationsSaved data recordsBottom tab or menu
SyncSync status and actionsBottom tab or menu
SettingsApp configurationMenu or gear icon
MoreAdditional optionsMenu
  • Bottom tabs - Quick access to main sections
  • Menu drawer - Swipe from left or tap hamburger (☰)
  • Back button - Return to previous screen
  • Floating action button - Quick actions (+ button)

Syncing App Bundle

Before using forms, sync the app bundle from the server:

Initial Sync

  1. Go to Sync screen
  2. Tap "Sync Now" or "Download App Bundle"
  3. Wait for download - Progress indicator shows status
  4. Forms become available after successful sync

Sync Information

The sync screen shows:

  • Last sync time - When data was last synced
  • Pending uploads - Observations waiting to sync
  • Server status - Connection health
  • App bundle version - Currently installed version

Manual Resync

To force a fresh download:

  1. Go to Sync screen
  2. Tap "Resync" or "Force Download"
  3. Confirm the action
  4. Wait for completion

Working with Forms

Viewing Available Forms

  1. Go to Forms screen
  2. See list of forms from current app bundle
  3. Each form shows:
    • Form name/title
    • Description (if available)
    • Icon (if configured)

Starting a New Form

  1. Tap on a form from the list
  2. Form opens in the form player
  3. Fill in fields as required
  4. Navigate through form sections

Form Field Types

The Formulus app supports various field types:

Field TypeDescriptionInput Method
TextSingle/multi-line textKeyboard
NumberNumeric valuesNumber keyboard
DateDate selectionDate picker
TimeTime selectionTime picker
SelectSingle choiceDropdown/radio
Multi-selectMultiple choicesCheckboxes
PhotoCamera captureCamera
GPSLocation captureGPS sensor
SignatureDigital signatureTouch drawing
AudioVoice recordingMicrophone
VideoVideo recordingCamera
FileFile attachmentFile picker
QR CodeScan QR/barcodeCamera scanner

Form Navigation

  • Swipe left/right - Navigate between sections
  • Next/Previous buttons - Move through form
  • Progress bar - Shows completion status
  • Section tabs - Jump to specific section (if enabled)

Saving a Form

Save as Draft

  1. Tap "Save Draft" at any time
  2. Form is saved locally with current data
  3. Can resume later from Observations screen
  4. Draft status shown in observation list

Submit/Finalize

  1. Complete all required fields
  2. Tap "Submit" or "Finalize"
  3. Validation runs - Errors shown if any
  4. Observation saved as pending upload
  5. Will sync when connection available

Form Validation

Forms may have validation rules:

  • Required fields - Must be filled before submit
  • Format validation - Email, phone number formats
  • Range validation - Min/max values
  • Conditional logic - Fields shown based on other answers

Validation errors:

  • Red highlight on invalid fields
  • Error messages below fields
  • Cannot submit until resolved

Managing Observations

Viewing Observations

  1. Go to Observations screen
  2. See list of all saved observations
  3. Each entry shows:
    • Form name
    • Date/time created
    • Status (draft, pending, synced)
    • Key data fields

Observation Status

StatusIconDescription
Draft📝Incomplete, can edit
Pending⏳Complete, awaiting sync
Syncing🔄Currently uploading
Synced✅Successfully uploaded
Error❌Sync failed, retry needed

Editing Observations

Edit Draft

  1. Tap on draft observation
  2. Form opens with saved data
  3. Make changes
  4. Save or Submit

Edit Pending (if allowed)

  1. Tap on pending observation
  2. May need to "Unlock" for editing
  3. Make changes
  4. Re-submit

Deleting Observations

  1. Long-press on observation or tap menu (⋮)
  2. Select "Delete"
  3. Confirm deletion

Note: Synced observations may not be deletable locally.

Syncing Data

Automatic Sync

The app automatically syncs when:

  • Network becomes available
  • App is opened (background sync)
  • Periodically (if configured)

Manual Sync

  1. Go to Sync screen
  2. Tap "Sync Now"
  3. Watch progress - Upload count, status
  4. Check results - Success/failure messages

Sync Process

  1. Pull - Download new forms and server data
  2. Push - Upload pending observations
  3. Attachments - Upload photos, audio, etc.
  4. Confirmation - Server acknowledges receipt

Sync Indicators

  • Sync icon in status bar - When syncing
  • Badge on sync tab - Pending upload count
  • Last sync time - On sync screen
  • Individual observation status - In list

Offline Mode

When offline:

  • ✅ Can fill out forms
  • ✅ Can save observations locally
  • ✅ Can view previously synced data
  • ❌ Cannot upload new data
  • ❌ Cannot download new forms

Data syncs automatically when connection returns.

Attachments

Capturing Photos

  1. Tap photo field in form
  2. Camera opens
  3. Take photo or select from gallery
  4. Review and confirm
  5. Photo attached to observation

Capturing GPS Location

  1. Tap GPS field in form
  2. Location permission requested (first time)
  3. Wait for GPS fix
  4. Coordinates captured (lat, long, accuracy)
  5. May show on map preview

Recording Audio

  1. Tap audio field in form
  2. Microphone permission requested (first time)
  3. Tap record to start
  4. Speak clearly
  5. Tap stop when done
  6. Review and confirm

Capturing Signatures

  1. Tap signature field in form
  2. Signature pad opens
  3. Sign with finger on screen
  4. Tap "Done" to save
  5. Tap "Clear" to retry

Settings

Server Settings

  • Server URL - Synkronus server address
  • Test Connection - Verify connectivity

User Settings

  • Username - Current user
  • Change Password - Update credentials
  • Logout - Clear session

Sync Settings

  • Auto-sync - Enable/disable automatic sync
  • Sync on WiFi only - Save mobile data
  • Sync interval - How often to sync

App Settings

  • Notifications - Enable/disable alerts
  • Theme - Light/dark mode
  • Language - App language
  • Clear cache - Free up storage

Best Practices

Data Collection

  1. Sync before fieldwork - Get latest forms
  2. Check battery - Ensure sufficient charge
  3. Test GPS outdoors - Better accuracy
  4. Save frequently - Avoid data loss
  5. Sync when possible - Don't wait too long

Offline Work

  1. Sync before going offline
  2. Save observations as you go
  3. Check pending count before leaving field
  4. Sync immediately when back online

Data Quality

  1. Fill all required fields
  2. Double-check entries
  3. Take clear photos
  4. Verify GPS accuracy
  5. Review before submitting

Related Content