Skip to content

Best Practices & Troubleshooting

Best Practices

Form Design

  • Keep Keys Simple: Use simple, camelCase keys for fields (e.g., firstName, spiritualHistory). This makes Lava templates and Query Parameters much easier to manage.
  • Use Sections: Break long forms into sections. It improves readability and allows you to hide large chunks of irrelevant questions using Conditional Logic.
  • Progressive Disclosure: Don't ask "List your allergies" immediately. Ask "Do you have allergies?" first, and show the list field only if they say Yes.

Performance

  • Defined Types: Prefer Rock Defined Types for dropdowns over hard-coded custom options. It makes maintenance easier centralize.
  • Clean Up: Archive old forms instead of deleting them to preserve historical entry data.

Security

  • Least Privilege: Only grant Interact to All Users if the form is truly public.
  • Sensitive Data: Be careful with "Long Text" fields asking for sensitive info. Remember that form entries are stored in the plugin tables, not standard Person Attributes (unless mapped via workflow).

Troubleshooting

Common Issues

Issue: "I updated the form, but users don't see the changes." * Cause: Caching or existing drafts. * Fix: Rock caches block settings. Clear the Rock cache. Also, users with an existing draft might be seeing the version of the form from when they started.

Issue: "My workflow isn't triggering." * Cause: Trigger configuration. * Check: 1. Go to Form Type > Workflow Triggers. 2. Ensure "Is Active" is Checked. 3. Ensure the Trigger Type is correct (usually "Submitted"). 4. Check System Jobs to ensure LaunchFormTypeChangeWorkflows is running.

Issue: "The 'Advanced Form' workflow action is stuck waiting." * Cause: The user might have created a new entry instead of linking to the workflow request, or the Entry Qualifiers don't match. * Fix: Check the workflow log. Verify the user submitted the form after the workflow started waiting.

Issue: "Date conditions aren't working." * Cause: Date format mismatch. * Fix: Ensure the condition is comparing against a valid date format. Use the Date picker in the condition builder rather than typing text.

API Reference

Key Endpoints

  • GET api/RedeemerTech_Forms_FormType/GetFullForm/{id}: Returns the complete form definition JSON.
  • POST api/RedeemerTech_Forms_FormEntry/SaveEntry: Submits a form entry. payload must match FormEntryBag structure.

Javascript Events

The FormEntry web component emits events you can listen to in custom scripts: * received-form: When form definition loads. * saved-form: When a draft is saved. * submitted-form: When successfully submitted.

Glossary

  • Form Type: The template/definition of a form.
  • Form Pack: A container for multiple Form Types.
  • Entry: A single submission instance.
  • Key: The unique string identifier for a form element.
  • Slug: (Future) URL-friendly name.
  • Token (p): Person Action Identifier used for anonymous authentication.