Purpose
This document defines the recommended baseline process and best practices for upgrading the Serenity applications in ServiceNow. The objective is to minimize upgrade risk, properly review skipped records, validate application functionality, and ensure a smooth deployment across Development, QA/Test, and Production environments.
1. Pre-Upgrade Planning
Before scheduling any upgrade activities, complete the following steps.
Verify Application Compatibility
Navigate to the ServiceNow Store and verify that the version of the Serenity applications is certified for the target ServiceNow release.
For example:
If the instance is running in Australia, verify that the Serenity applications are certified for Australia.
If upgrading to a newer family release, confirm that an application version supporting that release is available before proceeding.
Upgrading an instance before verifying application compatibility may introduce unexpected issues.
Depending on which Serenity apps are installed and how many, you need to check each one (see the example in the screenshot and the links below).
Serenity Core https://store.servicenow.com/store/app/763aefe21b246a50a85b16db234bcb5b
Inspection and Audit Management https://store.servicenow.com/store/app/9c8ba3aa1b246a50a85b16db234bcbaf
Environmental, Health, & Safety Incident & Investigation https://store.servicenow.com/store/app/d6d8e32e1be06a50a85b16db234bcb2b
Serenity AI https://store.servicenow.com/store/app/ed9a6b661b246a50a85b16db234bcbf9
Coordinate with the Platform Team
Meet with the Platform Team to define:
Target upgrade date
Upgrade window
Expected downtime
Roles and responsibilities
Rollback strategy (if applicable)
Communication plan
Typical responsibilities include:
Platform Team
Perform the ServiceNow family upgrade.
Upgrade required plugins.
Assist with platform-level validation.
Approve upgrades across environments.
Serenity Services Team
Upgrade Serenity applications.
Review skipped records.
Resolve upgrade conflicts.
Perform regression testing.
Prepare Update Sets containing any required fixes.
2. Development Environment
Development should always be upgraded first.
No work should be performed in QA or Production until Development has been completely validated.
Upgrade the Serenity Applications
Upgrade all Serenity applications to the desired version.
Navigate to the Application Manager module (plugins module)
Select the desired app
Select the desired Serenity version
Click Upgrade
Upgrade Required Plugins
Before reviewing skipped records, verify whether additional platform plugins also require upgrades.
Common examples include:
UI Builder
App id: sn_ui_builder
Workspace-related plugins
Other dependencies introduced by the ServiceNow family release
Suggested: These should be upgraded before beginning skipped record analysis, as plugin updates may resolve or introduce skipped records.
3. Review Skipped Records
Skipped Records should always be reviewed immediately after the application and required plugins have been upgraded.
Each skipped record should be evaluated to determine whether:
The customer's customization should remain.
The new OOTB version should replace the customization.
The customization should be merged with the new OOTB version.
Additional changes are required.
Typical records to review include:
Business Rules
Client Scripts
Script Includes
ACLs
Dictionary records
Workspace pages
UI Builder components
UI Actions
Notifications
Flow Designer artifacts
Record Producers
Catalog Items
Scripted REST APIs
Scheduled Jobs
If any issues are identified, implement the required fixes in a dedicated Update Set.
For more information about reviewing skipped records refer to ServiceNow official documentation: https://www.servicenow.com/docs/r/platform-administration/upgrade-center/uc-access-rl.html
4. Development Validation
Once all skipped records have been reviewed and resolved, perform comprehensive regression testing.
Regression testing should include every Serenity application.
Examples include:
Create records.
Update records.
Close records.
Verify business rules.
Verify notifications.
Verify PDF generation.
Verify Workspace functionality.
Verify Mobile functionality (if applicable).
Verify integrations.
Verify scheduled jobs.
Verify dashboards and reports.
Security Validation
Security testing is equally important.
Impersonate multiple users representing different roles to verify:
Users have access to the correct modules.
Users can only see records they should be allowed to access.
Users have the correct Create, Read, Update, and Delete permissions.
Users do not receive additional permissions unexpectedly.
Users are not missing permissions required to perform their daily work.
Typical personas include:
General User
Team Leader
Shop Safety
Core Safety
Group Leader
Site Administrator
EHS Administrator
5. QA / Test Environment
Only after Development has been successfully validated should the team proceed with QA or Test.
Request approval from the Platform Team before upgrading the QA/Test environment.
Once approved:
Upgrade the Serenity applications.
Upgrade required plugins.
Move all approved Update Sets from Development.
No new fixes should be developed directly in QA/Test.
QA/Test should represent exactly what will be promoted to Production.
User Acceptance Testing (UAT)
Application Owners and business representatives should perform User Acceptance Testing.
Recommended testing includes:
Daily business processes
End-to-end workflows
Security validation
Notifications
Reports
Dashboards
Workspace
Mobile (if applicable)
Integrations
All critical issues should be resolved in Development before promoting fixes to QA.
6. Production Upgrade
After QA/Test validation has been completed successfully, request approval from the Platform Team to upgrade Production.
Recommended best practices include:
Schedule the upgrade during periods of low business activity.
Avoid business-critical hours whenever possible.
Ensure all stakeholders are aware of the maintenance window.
Confirm rollback procedures before beginning.
After the Production upgrade:
Upgrade Serenity applications.
Upgrade required plugins (if applicable).
Move the approved Update Sets.
Perform a production smoke test immediately after deployment.
7. Communication Best Practices
Prior to the Production deployment, send communication to all affected users.
Recommended information includes:
Planned maintenance window
Expected downtime
Summary of new features
Known impacts
Expected user actions (if any)
Contact information for reporting issues
After deployment, send a follow-up communication confirming completion of the upgrade.
Communication email: Example (Source ServiceNow)
Clear and consistent communication is essential for ensuring a smooth transition during the go-live. By keeping employees informed about the timeline, objectives, and expected outcomes, organizations can reduce uncertainty, address potential concerns, and ensure that everyone feels prepared and supported throughout the process.
Utilizing multiple communication channels, such as emails, team meetings, and intranet updates, can enhance message reach and engagement and promotes a shared commitment to the success of the go-live.
8. Release Notes
Release Notes describing new functionality, enhancements, bug fixes, and known issues should be reviewed prior to every upgrade.
The latest Release Notes are available at:
Release Notes:
ServiceNow Store: https://store.servicenow.com/store/apps?q=serenity
Serenity Docs: https://docs.serenityops.com/docs/getting-started-with-serenity
If additional information is needed, or if the Release Notes are unavailable, please contact the Serenity Product Team, who can provide the latest documentation and upgrade guidance.
Best Practices Summary
Verify application compatibility before upgrading.
Upgrade Development first.
Upgrade required plugins before reviewing skipped records.
Review every skipped record carefully.
Place all fixes into dedicated Update Sets.
Perform full regression testing in Development.
Validate security using impersonation across multiple user roles.
Obtain Platform Team approval before upgrading QA/Test and Production.
Do not develop or fix issues directly in QA/Test or Production.
Perform User Acceptance Testing in QA/Test.
Schedule Production upgrades during low-usage windows.
Communicate planned maintenance and release information to end users.
Review Release Notes before every upgrade.
Maintain close coordination between the Platform Team, Application Owners, and the Serenity Services Team throughout the upgrade process.