Mobile migration from Madrid to New York and later releases
Summarize
Summary of Mobile migration from Madrid to New York and later releases
This guide explains the mobile application migration process when upgrading your ServiceNow instance from the Madrid release to New York or later versions. The migration activates the Mobile Agent Native Client plugin, which transitions your mobile apps to a new mobile hierarchy and schema to leverage enhanced mobile features and continued Studio editing capabilities.
Show less
The upgrade automatically updates unmodified base system mobile applications to the new design, enabling immediate use with Studio. However, modified base system applications and any custom applications created in Madrid require running a mobile migration script to become fully compatible and configurable in Studio.
Key changes during upgrade
- Activation of Mobile Agent Native Client plugin, creating new tables for native clients, navigation bars, notifications tabs, and settings tabs to support the updated mobile architecture.
- Introduction of application launchers and configurable navigation bars replacing legacy folders and applications.
- Legacy mobile applications and folders are converted into applet launchers with horizontal UI sections accessible via navigation bar tabs.
- Form, map, and calendar applets are migrated to new screen and item stream records to align with the New York schema.
- Removal of deprecated fields from screen and item configuration records to clean up legacy data.
Post-upgrade requirements and considerations
- Run the Mobile Migration Script: This script transforms your custom and modified applications to the new mobile schema. It must be run separately for each scoped mobile application.
- Testing and Validation: Thoroughly test all modified and custom mobile applications post-upgrade to ensure continued functionality.
- Debug Upgrade Feature: Use this tool to diagnose upgrade issues quickly.
- Review Skipped Records: Records you have customized are not overwritten during upgrade but logged as skipped. You should review and resolve these to maintain functionality.
- Collision Resolution: After running the migration script, resolve any collisions caused by modified base system records to complete migration.
- Regression Testing: Perform regression tests on applets, UI policies, and functions to confirm usability and stability after migration.
Practical impact for ServiceNow customers
This migration enables customers to take advantage of enhanced mobile capabilities introduced in New York and later releases, including improved navigation, applet launchers, and better integration with Studio for app development and editing.
Proper execution of the migration script and thorough post-upgrade testing are critical to ensure that both base system and custom mobile applications continue to operate smoothly and are fully compatible with the new mobile architecture.
Customers should carefully document any customizations made to mobile apps prior to upgrade and leverage available tools and training to address skipped records and collision resolution effectively.
Migrate your mobile applications in New York or later releases to take advantage of the improved features and continue editing within Studio.
Changes made during your upgrade
- Native clients
- Adds the Native Clients [sys_sg_native_client] table. Records on this table represent the available native clients; Mobile Agent, Now Mobile, and Mobile Onboarding.
- Navigation bar
- Adds the navigations [sys_sg_navigation] table. Records on this table represent a navigation bar for each of the native clients. Records on this table during the migration have their Legacy application [legacy_application] field enabled.
- Notifications tab
- Adds the notifications tabs [sys_sg_notifications_tab] table. Records on this table represent a tab for notifications on each navigation bar.
- Settings tab
- Adds the settings tabs [sys_sg_settings_tab] table. Records on this table represent a tab for settings on each navigation bar.
This upgrade includes new features such as application launchers and a configurable navigation bar. Any unmodified base system mobile applications installed on your instance are automatically updated to work with the new design, and can be used with Studio right away. For more detail on the mobile hierarchy used in New York and later, see Mobile hierarchy.
Modified base system applications, and applications that you have created in Madrid will continue to work after the upgrade. These applications will not be configurable in Studio until after you have run the mobile migration script.
Post-upgrade considerations
After an upgrade, consider the following information to confirm that your mobile implementation is working as expected, and ensure that mobile migration script runs.
- Modified base system applications
- Document any changes you have made to mobile applications provided by ServiceNow, as well as any applications you have created. Test each of these applications to ensure that they continue to function as you expect.
- Use the Debug Upgrade feature
The debug upgrade feature can help you to quickly diagnose upgrade issues. For information on this feature, see Debug upgrade.
A video training course on this tool is available. To view this course, see Using Debug Upgrade
- Review skipped records
To prevent overriding your customizations, the upgrade process does not update records that you have modified. Instead, the upgrade process notes this skipped record in the upgrade logs.
A video training course on resolving skipped records is available. To view this course, see Upgrade Skipped Records.
- Review functionality after upgrade
- Once you have upgraded your instance and run the migration script, regression testing can help ensure that your users can continue to work as expected after an upgrade. A regression test is a review of your applets, screen ui policies, and functions to make sure that they are working as intended.
Running Mobile migration script
This script converts your custom applications and any modified base system application to the new mobile schema available in the New York release. The script only changes the current scope when it runs. If you have more than one scoped mobile application, you must run the script for each scope.
After an upgrade, the option to run the migration script appears when you first access a
custom application, or a base system application that you have modified. For example, when
opening a modified or custom applet record. You can also see the migration prompt when accessing
the applet picker in Studio by browsing to and clicking the pop-out icon (
). The migration prompt displays if any of the applets shown the picker require
migration.
After the script completes, you may be prompted to resolve collisions detected by the migration process. Collisions are records created by ServiceNow that you have modified, and are not automatically upgraded. Collisions can only occur when you have modified a base system application before your upgrade to New York or later releases.
Changes made by the mobile migration script
Click Migrate to start the migration script for the current scope. The migration script migrates all records within the scope, not just the applet you have opened.
- Applications and folders transition to applet launchers
The legacy Madrid schema used mobile applications and folders to organize your applets. The Now Mobile schema, uses applet launcher screens, which are divided into UI sections. Applet launcher is accessed by tapping on tabs in the navigation bar which appears at the bottom of your app screens.
Figure 1. Changes to applications in the New York schema The migration script creates an applet launcher for each mobile application record. The script converts each folder in the original mobile application to a new horizontal icon section within that applet launcher. The script then creates an icon in the icon section for each applet with the folder. Hidden screens do not appear in the icon section. The script then adds a tab to the navigation bar for each of the new applet launchers.
The example image shows how the incidents application appears after the migration process. The original folders (My Incidents and Group Incidents) display as UI sections in the Incidents applet launcher. These UI sections can scroll horizontally to show as many applets as needed. The Incidents application is accessible by tapping the Incidents tab in the navigation bar.
After migration, the script removes the legacy Folder [sys_sg_folder] and Mobile Application [sys_sg_application] records.
For more detail on the navigation bar, applet launchers and their UI sections, see Navigation bar, and Launcher screens.
- Form migration
- The Form applet replaces the root detail screens used to view record forms in the Madrid release. The migration creates a form screen [sys_sg_form_screen] record. The script creates segments for each embedded screen in the original main detail screen. Any button [sys_sg_button] records associated to the original main detail screen change to associate with the new form applet.
- Map migration
- Map applets did not use an item view to display fields in map cards in the Madrid release. The migration script creates an item view[sys_sg_item_view] record for each map applet using the Title, Tag, Sub-title, and Info fields from the original map applet.
- Calendar migration
- The migration script creates time span item stream [sys_sg_time_span_item_stream] records for each calendar, and associates the calendars original data item to the new item stream. The migration script also creates a form applet [sys_sg_form_screen] record, and migrates the buttons from the calendars original embedded screen to the new form.
- Item streams and Item configurations
The migration script creates an item stream [sys_sg_item_stream] record for each screen in the scoped application. The original data item record associated with the legacy application changes to associate with the new item stream record. The script creates time span item stream [sys_sg_time_span_item_stream] records for each calendar screen, and location item stream [sys_sg_location_item_stream] records for map screens. These two tables extend from the item stream table, but are used specifically for these screen types.
- Screen Cleanup
- The following fields are no longer used in Screen records. The script removes these fields from call records on the Screen [sys_sg_screen] table.
- User Roles [application_roles]
- Order [order]
- Parent [parent]
- Parent table [parent_table]
- Data Item [sys_sg_data_item]
- Hidden [hidden]
In addition, the script also removes values from the following fields on Map screen [sys_sg_map_screen] records:- Data item table [data_item_table]
- Title [title]
- Sub-title [subtitle]
- Info [info]
- Location [location]
- Tag [tag]
- Tag font color [tag_font_color]
- Tag background color[tag_background_color]
- Tag Style [tag_style]
- Phone [phone]
- Pin color type [pin_color_type]
- Pin color [pin_color]
The script removes values from the following fields on Item configuration [sys_sg_master_item] records:- Table [table]
- Screen [screen]
- Condition [condition]
- Condition Order [condition_order]
The script removes the value in the Item View [item_view] field of Details screen [sys_sg_details_screen] records.
The script removes the value in the Item View [item_view] field of List screen [sys_sg_list_screen] records.
The script removes the value in the Data Item [data_item] field of Item View [item_view] records.
More Resources
For more information on the migration process, see the Mobile Migration Guide for New York on the ServiceNow community site. https://community.servicenow.com/community?id=community_article&sys_id=f5121a33dba7f788fff8a345ca961957