Skip to main content

Troubleshooting

This guide helps resolve common issues with the Change Reasons feature, from configuration problems to user experience challenges.

Configuration Issues​

Change Reason Modal Doesn't Appear​

Problem: Clicking "Publish" doesn't show the change reason modal

Root Cause Check: Is the change reason feature enabled in your system?

Solution Steps:

  1. For Administrators: Check System Settings → Workflow → "Require change reason when publishing forms?"

    • If unchecked: This is expected behavior - forms publish directly without change reasons
    • If checked: Continue to technical troubleshooting steps below

  2. For Users: Ask your system administrator about the current configuration

    • The feature may be intentionally disabled
    • Your organization may be using streamlined publishing workflow

Technical Troubleshooting (if feature should be enabled):

  • Refresh the page and try again
  • Clear browser cache and cookies
  • Ensure JavaScript is enabled in your browser
  • Try a different browser or incognito/private browsing mode
  • Check for browser console errors (F12 → Console tab)

Feature Inconsistently Available​

Problem: Change reason prompts appear for some users but not others

Possible Causes:

  • Browser Caching: Some users may have old page versions cached
  • Permission Levels: Verify all affected users have form publishing permissions
  • Session Issues: Users may need to log out and back in

Solutions:

  • Have all users clear browser cache and cookies
  • Verify user permissions in System Settings → User Management
  • Restart user sessions (log out and back in)
  • Check for any custom user group settings affecting the feature

Publishing Issues​

Validation Errors​

"Reason must be at least 10 characters"​

Cause: Change reason is too short

Solutions:

  • Add more detail about the specific changes made
  • Explain the context or purpose behind the changes
  • Include impact information if relevant

Example Fix:

  • Instead of: "Fix" (3 characters)
  • Use: "Fixed validation error preventing international phone number submissions" (76 characters)

"Reason cannot exceed 500 characters"​

Cause: Change reason is too long

Solutions:

  • Focus on the most important changes
  • Remove unnecessary words while keeping key information
  • Use abbreviations for common terms (UI, API, etc.)
  • Consider bullet points or numbered lists for multiple changes

Example Fix:

  • Instead of: "Updated the user interface to improve the user experience by reorganizing the form layout to make it more intuitive for users who are completing the form on mobile devices, and also fixed several validation issues that were preventing users from successfully submitting the form when they entered phone numbers in international format..." (too long)
  • Use: "Enhanced mobile UI layout for better UX and fixed validation issues preventing international phone number submissions" (116 characters)

"Reason is required"​

Cause: Empty change reason field

Solutions:

  • The field cannot be left blank when change reasons are required
  • You must provide some text describing the changes
  • The modal cannot be dismissed without entering a reason

Publishing Failures​

Problem: Form doesn't publish after entering change reason

Diagnostic Steps:

  1. Check Internet Connection: Ensure stable connectivity
  2. Verify Permissions: Confirm you have publishing rights for the form
  3. Review Form Content: Check for validation errors in the form itself
  4. Check System Status: Verify OSPROV system availability

Solutions:

  • Connection Issues: Retry publishing after ensuring stable internet
  • Permission Issues: Contact administrator to verify your publishing permissions
  • Form Validation: Fix any form-level validation errors before publishing
  • System Issues: Try again later or contact IT support

Problem: Cannot dismiss or close the change reason modal

Expected Behavior:

  • The modal is designed to be persistent when change reasons are required
  • This ensures no forms are accidentally published without documentation

Solutions:

  • To Publish: Enter a valid change reason (10-500 characters) and click "Publish Form"
  • To Cancel: Look for a "Cancel" or "Close" button to return to the form without publishing
  • If Stuck: Refresh the page to start over (form will remain unpublished)

Access and Display Issues​

Change History Not Visible​

Problem: Can't see change history for a form

Troubleshooting Checklist:

  • ✅ Form Status: Has the form been published at least once?
  • ✅ Permissions: Do you have view permissions for the form?
  • ✅ Feature History: Were change reasons enabled when the form was published?
  • ✅ Browser Issues: Try refreshing the page

Solutions:

  • Unpublished Forms: Only published forms have change history
  • Permission Issues: Contact administrator to verify your access level
  • Legacy Forms: Forms published before change reasons were enabled won't have change history
  • Display Problems: Clear browser cache or try a different browser

Truncated Change Reasons​

Problem: Can only see partial change reasons in form listings

Expected Behavior: This is normal - full reasons are available on hover or in detailed view

Solutions:

  • In Form Listings: Hover over truncated text to see the full reason
  • For Full Details: Click on the form name to view complete change history
  • Export Needs: Contact administrator about reporting options for full change history

Browser and Technical Issues​

JavaScript Errors​

Problem: Change reason modal appears broken or non-functional

Diagnostic Steps:

  1. Open Browser Console: Press F12 and check Console tab for errors
  2. Check JavaScript: Ensure JavaScript is enabled in browser settings
  3. Browser Compatibility: Verify you're using a supported browser

Solutions:

  • Script Errors: Refresh the page or clear browser cache
  • JavaScript Disabled: Enable JavaScript in browser settings
  • Old Browser: Update to a current version of Chrome, Firefox, Safari, or Edge
  • Extensions: Try disabling browser extensions that might interfere

Performance Issues​

Problem: Change reason modal loads slowly or times out

Possible Causes:

  • Slow internet connection
  • High system load
  • Large form with complex validation

Solutions:

  • Connection: Verify internet speed and stability
  • Timing: Try again during off-peak hours
  • Browser: Close other tabs or applications consuming resources
  • Network: Contact IT if organizational network issues are suspected

Data and Audit Issues​

Missing Change Information​

Problem: Some form changes don't have associated change reasons

Possible Explanations:

  • Feature Timeline: Changes made before change reasons were enabled
  • Configuration Changes: Periods when the feature was temporarily disabled
  • Legacy Data: Historical changes from before system implementation

Not a Bug: This is expected behavior for pre-existing data

Change Attribution Issues​

Problem: Wrong user listed for changes, or user information missing

Possible Causes:

  • Session Issues: User was logged in under different account
  • Bulk Operations: Changes made through administrative tools
  • Data Migration: Historical data imported from other systems

Solutions:

  • Current Issues: Verify users are logged in with correct accounts
  • Historical Issues: Contact administrator for data correction if needed
  • Audit Concerns: Document any attribution issues for compliance purposes

Getting Help​

Internal Support​

  1. Check Documentation: Review other sections of this Change Reasons guide
  2. Ask Colleagues: Consult team members familiar with the feature
  3. Administrator Support: Contact your system administrator for configuration issues
  4. IT Support: Reach out for technical or browser-related problems

Information to Provide When Seeking Help​

For Configuration Issues:

  • Your user role and permissions
  • Whether the issue affects all users or specific individuals
  • Browser type and version
  • Steps you've already tried

For Publishing Issues:

  • Exact error messages received
  • Form name and ID (if available)
  • Change reason text you were trying to submit
  • Browser console errors (F12 → Console)

For Access Issues:

  • Specific forms or areas you cannot access
  • Your user permissions level
  • Whether the issue is new or ongoing
  • Other users experiencing similar problems

Escalation Guidelines​

Level 1 - Self Service: Documentation, browser troubleshooting, cache clearing Level 2 - Team Support: Colleagues, local administrators, permission verification
Level 3 - IT Support: Technical issues, system configuration, integration problems Level 4 - Vendor Support: Platform bugs, feature requests, complex technical issues

By following this troubleshooting guide, most Change Reasons issues can be resolved quickly, ensuring smooth form publishing workflows and maintaining audit trail integrity.