Migration to ITSM Mobile Agent 5.0.3

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Migration to ITSM Mobile Agent 5.0.3

    The migration to ITSM Mobile Agent 5.0.3 introduces the Next Experience theme and enhances accessibility compliance. This update modernizes legacy components by migrating icon sections, UI parameters, and card views to newer, more flexible formats that support theming, accessibility, and improved user experience on mobile devices.

    Show full answer Show less

    Key Features

    • Icon Sections Migration: Legacy icon sections are converted to navigation sections with better grouping and color variables, improving organization for on-call scheduling and incidents.
    • UI Parameters Migration: Legacy UI parameters are replaced by new input form screens that simplify parameter definition, support theming, and enhance accessibility.
    • Card Views Migration: Legacy card views are updated to mobile views that use color variables and allow styling via UI rules instead of UI styles.
    • Button Updates: Positive action buttons now use a “positive” emphasis rather than “primary” to align with the new design language.

    Migration Process

    When upgrading to version 5.0.3, the system automatically triggers a clean upgrade script that performs the following:

    • For icon sections, it compares legacy and new configurations, deactivating legacy or new records based on detected customizations to avoid conflicts.
    • For UI parameters, it verifies customization status of button instances and related records to selectively deactivate legacy or new configurations accordingly.
    • For card views, it examines legacy item views and associated UI styles, reverting or retaining configurations based on customization to maintain consistency.

    Important Considerations for Customers

    • Custom icon sections, button flows, or item views not part of the default configuration remain functional but may lack full Next Experience theme support and accessibility compliance.
    • Customers with customized default icon sections, UI parameters, or item views must manually review and migrate their customizations to the new navigation sections, input form screens, and mobile cards respectively to ensure a consistent and accessible user experience.
    • Failure to migrate customizations may result in a mixed user experience that is not fully compatible with the new theme and can cause accessibility issues.

    Practical Benefits

    By migrating to ITSM Mobile Agent 5.0.3, ServiceNow customers gain a modernized mobile interface aligned with the Next Experience design principles, improved accessibility compliance, and simplified customization through new configuration paradigms. This ensures a consistent, user-friendly mobile experience for ITSM agents.

    Migration to ITSM Mobile Agent 5.0.3 enables the Next Experience theme and accessibility compliance in ITSM Mobile Agent.

    This migration includes the following component changes:
    • Migration of legacy icon sections to new icon sections. It includes better grouping of icon sections for on-call scheduling and incidents along with color variables for icons.
    • Migration of legacy UI parameters to new input form screens. It simplifies the way parameters are defined, enables theming on the input form screen, and supports accessibility enhancements by Mobile Platform.
    • Migration of legacy card views to mobile views. It allows using color variables as per theme.
    • All styling changes can be done through UI rules instead of UI styles.
    • For buttons that perform a positive action, button emphasis has changed from primary to positive.
    When customers migrate from any older version to ITSM Mobile Agent 5.0.3, the following steps are automatically performed:
    • When the plugin.upgraded event is triggered for the ITSM Mobile Agent (sn_itsm_mobile_agt) application, the Run clean upgrade for ITSM Mobile Agent script action is run.
    • This script action invokes the following upgrade APIs:
      • For legacy icon sections to new navigation sections, the cleanUpgradeIconSections() method from the sn_itsm_mobile_agt.MobileUtahUpgradeEngine script include.
      • For old ui parameters to new input form screen, cleanUpgradeButtonInstance() method from the sn_itsm_mobile_agt.MobileUtahUpgradeEngine script include.
      • For legacy cards to new mobile views, cleanUpgradeLegacyCards() method from the sn_itsm_mobile_agt.MobileUtahUpgradeEngine script include.
      • A map with key value pairs, sn_itsm_mobile_agt.MobileIconSectionMigrationConstant, is introduced where the key is the sys_id of the legacy default configuration and the value is an object with a comma-separated list of metadata for the corresponding new default configuration that is introduced in the upgrade process.
    • After the script action is run and performs all the required actions, it is deactivated so that it isn’t run again on future upgrades.

    Migration of legacy icon sections to navigation sections

    In this case, the sn_itsm_mobile_agt.MobileIconSectionMigrationConstants script include contains the following key value pairs:
    • Key: sys_id of the legacy default sys_sg_icon_section record.
    • Value: Object with a comma-separated list of sys_ids of sys_sg_navigation_section and sys_sg_applet_launcher_m2m_section records.
    The Run clean upgrade for ITSM Mobile Agent script action upgrade script runs to perform the following steps for each key in the map:
    1. Check the following records for customizations.
      • Legacy default sys_sg_icon_section record.
      • Compare if the legacy default icon section has at least one new or one less sys_sg_applet_launcher_m2m_section record when compared to the new default icon section.
    2. Based on customizations, one of the following steps is performed.
      • If any of the above records are customized, the script deactivates the new default sys_sg_navigation_section record.
      • If none of the above records are customized, the script deactivates the legacy default sys_sg_icon_section record.
    Note:
    • Custom icon sections that are not available by default continues to function but may not support Next Experience theme and accessibility compliance. Customers must migrate them to navigation sections for better experience.
    • For customized icon sections that are available by default, customers must manually review the legacy default icon sections that are still active and move their customizations to the new default navigation sections.
    • If customized icon sections are not migrated to the new navigation sections, then users will have a mixed experience that may not be fully compatible with the new Next Experience theme and can lead to accessibility issues.

    Migration of UI parameters to input form screen

    In this case, the sn_itsm_mobile_agt.MobileInputFormScreenMigrationConstants script include contains the following key value pairs:
    • Key: sys_id of the legacy default sys_sg_button_instance record.
    • Value: Object with comma-separated list of sys_ids of the new default sys_sg_button_instance record and other meta data.
    The Run clean upgrade for ITSM Mobile Agent script action upgrade script then runs to perform the following steps for each key in the map:
    1. Check the following records for customizations.
      • Legacy default sys_sg_button_instance record.
      • sys_sg_button record associated with the sys_sg_button_instance record.
      • sys_sg_ui_parameter and sys_sg_action_param_map records associated with the sys_sg_button record.
      • sys_sg_write_back_action_item record associated with the sys_sg_button record.
    2. Based on customizations, one of the following steps is performed.
      • If any of the above records are customized, the script deactivates the new default sys_sg_button_instance record.
      • If none of the above records are customized, the script deactivates the legacy default sys_sg_button_instance record.
    Note:
    • Custom button instance flows (UI Params) that are not available by default continues to function but may not support Next Experience theme and accessibility compliance. Customers must migrate them to input form screens for better experience.
    • For custom button instance flows (UI Params) that are available by default, customers must manually review the legacy default sys_sg_button_instance records that are still active and move their customizations to the new sys_sg_button_instance flow (refer to the map sn_itsm_mobile_agt.MobileInputFormScreenMigrationConstants). For configuring Input form screens on mobile, see Input form screen.
    • If customized UI parameters are not migrated to the new input form screens, then users will have a mixed experience that may not be fully compatible with the new Next Experience theme and can lead to accessibility issues.

    Migration of item views to new mobile cards

    In this case, the sn_itsm_mobile_agt.MobileIconSectionMigrationConstants script include contains the following key value pairs:
    • Key: sys_id of the legacy default sys_sg_item_view record.
    • Value: Object with a comma-separated list of sys_ids of sys_sg_form_screen and sys_sg_master_item records where legacy card (that is, item view) is referenced.
    The Run clean upgrade for ITSM Mobile Agent script action upgrade script then runs to perform the following steps for each key in the map:
    1. Check the following records for customizations.
      • Legacy default sys_sg_item_view record.
      • All sys_sg_ui_style records associated with the sys_sg_item_view record.
    2. If any of the mentioned records are customized, the script reverts the sys_sg_form_screen and sys_sg_master_item records to previous state only if these records are not customized.
    Note:
    • Custom item views that are not available by default will continue to function but may not support Next Experience theme and accessibility compliance. Customers must migrate them to input form screens for better experience.
    • For custom icon sections that are available by default, customers must manually review the old default flows which are still active and move their customizations to the new flow. For information about configuring cards on mobile, see Customize a screen using Mobile Card Builder.
    • If customized item views are not migrated to new mobile cards, then users will have a mixed experience that may not be fully compatible with the new Next Experience theme and can lead to accessibility issues.