Skip to main content

Publishing with Change Reasons

When change reasons are enabled by your administrator, you'll need to provide a reason every time you publish a form. This guide walks you through the complete publishing process.

Step-by-Step Publishing Process​

1. Prepare to Publish​

  • Navigate to Forms → Forms List
  • Find your draft form that you want to publish
  • Ensure all form content is finalized and tested

2. Initiate Publishing​

  • Click the "Publish" button (blue button with upload icon)
  • If change reasons are enabled, the "Change Reason" modal will appear automatically
  • If change reasons are not enabled, the form publishes immediately

3. Enter Change Reason​

When the change reason modal appears, you'll need to provide:

Required Information​

  • Reason for Change: Describe why you're publishing this form
    • Minimum: 10 characters
    • Maximum: 500 characters
    • Required: Cannot be left empty

Input Guidelines​

  • Be Specific: Mention key changes or improvements
  • Use Clear Language: Write in professional, understandable terms
  • Include Context: Add version-specific information if relevant
  • Mention Impact: Note how changes affect form users or processes

4. Submit Publication​

  • Review your reason for accuracy and completeness
  • Click "Publish Form" to confirm
  • The system will process the publication
  • You'll be redirected back to the forms list upon completion

5. Verify Publication​

  • Check that the form status has changed from "Draft" to "Published"
  • The publish button should no longer be visible for that form
  • Your change reason is now recorded in the system's audit trail

Change Reason Examples​

Excellent Examples ✅​

Initial Publications:

  • "Initial release of employee onboarding form with document upload, emergency contact fields, and automated email notifications to HR department"

Updates and Fixes:

  • "Fixed validation error preventing submission of forms with international phone numbers and updated help text for clarity"
  • "Added mandatory GDPR consent checkbox as required by new data protection policy effective March 2025"

Feature Enhancements:

  • "Enhanced mobile responsiveness for tablet users and added progress indicator for multi-step form completion"

Poor Examples ❌​

Too Vague:

  • "Update" (doesn't explain what was updated)
  • "Changes" (no specific information provided)
  • "Fix" (doesn't explain what was fixed)

Too Brief:

  • "v2" (just a version number)
  • "New" (doesn't describe what's new)
  • "Done" (provides no context)

Publishing Different Types of Changes​

First-Time Publications​

Focus on the form's purpose and key features:

  • "Initial release of quarterly performance review form with self-assessment, manager feedback, and goal-setting sections"

Bug Fixes​

Describe the problem and solution:

  • "Resolved calculation error in expense reimbursement total field that was causing incorrect submission totals"

Feature Additions​

Explain new functionality and its benefits:

  • "Added file attachment capability for supporting documents and integrated with document management system"

Compliance Updates​

Reference requirements and deadlines:

  • "Updated privacy policy consent language to comply with updated GDPR requirements effective January 2025"

User Experience Improvements​

Describe usability enhancements:

  • "Reorganized form sections for logical flow and added contextual help tooltips to reduce completion errors"

Special Publishing Scenarios​

Creating New Versions​

When publishing a new version of an existing form:

  • Reference the previous version if helpful
  • Explain what changed since the last version
  • Consider mentioning backward compatibility

Bulk Changes​

When making multiple related changes:

  • List the key changes in order of importance
  • Group related modifications together
  • Stay within the 500-character limit while being comprehensive

Emergency Updates​

For urgent fixes or critical updates:

  • Clearly indicate the urgency
  • Explain the issue being resolved
  • Mention any immediate actions required

Validation and Error Handling​

Common Validation Errors​

"Reason must be at least 10 characters"

  • Your reason is too short
  • Add more detail about the changes being made

"Reason cannot exceed 500 characters"

  • Your reason is too long
  • Condense while keeping essential information
  • Focus on the most important changes

"Reason is required"

  • You cannot leave the field empty
  • The modal cannot be dismissed without providing a reason

What Happens If Publishing Fails​

If the publishing process encounters an error:

  • The form remains in draft status
  • Your change reason is not saved
  • You'll need to address the error and try publishing again
  • The change reason modal will appear again when you retry

Closing the Modal:

  • Clicking outside the modal won't dismiss it
  • You must either provide a reason and publish, or explicitly cancel
  • Canceling returns you to the form without publishing

Browser Refresh:

  • If you refresh during the publishing process, you'll need to restart
  • Your change reason will not be preserved
  • The form will remain in its previous state

Tips for Effective Change Reasons​

Writing Efficiently​

  • Start with action verbs: "Added", "Fixed", "Updated", "Removed"
  • Use bullet points or numbered lists if listing multiple changes
  • Prioritize the most significant changes if space is limited

Team Collaboration​

  • Include ticket numbers or reference IDs when relevant
  • Mention team members involved in significant changes
  • Reference requirements or specifications that drove the changes

Future Reference​

  • Write as if you're explaining to your future self
  • Include enough context for someone else to understand
  • Consider how the reason will read in change history reports

Remember: Change reasons become part of your organization's permanent audit trail. Take time to write clear, professional, and informative reasons that will be valuable for future reference and compliance purposes.