# Mission Management Scenarios Before getting started with the development of mission management, be familiar with the following concepts related to mission management: - AbilityRecord: minimum unit for the system service to manage a UIAbility instance. It corresponds to a UIAbility component instance of an application. A maximum of 512 UIAbility instances can be managed on the system service side. - MissionRecord: minimum unit for mission management. One MissionRecord has only one AbilityRecord. In other words, a UIAbility component instance corresponds to a mission. - MissionList: a list of missions started from the home screen. It records the startup relationship between missions. In a MissionList, a mission is started by the mission above it, and the mission at the bottom is started by the home screen. - MissionListManager: system mission management module that maintains all the MissionLists and is consistent with the list in the recent task list. **Figure 1** Mission management ![mission-list-manager](figures/mission-list-manager.png) Missions are managed by system applications (such as home screen), rather than third-party applications. Users interact with missions through the recent task list. After creating a mission, users can perform the following operations in the recent task list: - Delete a mission. - Lock or unlock a mission. (Locked missions are not cleared when users attempt to clear all missions in the recent task list.) - Clear all missions in the recent task list. - Switch a mission to the foreground. A UIAbility instance corresponds to an independent mission. Therefore, when an application calls [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startability) to start a UIAbility, a mission is created. 1. To call [missionManager](../reference/apis-ability-kit/js-apis-application-missionManager-sys.md) to manage missions, the home screen application must request the ohos.permission.MANAGE_MISSIONS permission. For details, see [Requesting Permissions for system_basic Applications](../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications). 2. You can use **missionManager** to manage missions, for example, listening for mission changes, obtaining mission information or snapshots, and clearing, locking, or unlocking missions. ```ts import { missionManager } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { image } from '@kit.ImageKit'; import { promptAction } from '@kit.ArkUI'; import { hilog } from '@kit.PerformanceAnalysisKit'; const TAG: string = 'TaskManager'; const DOMAIN_NUMBER: number = 0xFF00; ``` ```ts private listenerId: number = 0; private missionId: number = 0; private listener: missionManager.MissionListener = { // Listen for mission creation. onMissionCreated: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionCreated-------'); }, // Listen for mission destruction. onMissionDestroyed: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionDestroyed-------'); }, // Listen for mission snapshot changes. onMissionSnapshotChanged: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionSnapshotChanged-------'); }, // Listen for switching the mission to the foreground. onMissionMovedToFront: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionMovedToFront-------'); }, // Listen for mission icon changes. onMissionIconUpdated: (mission: number, icon: image.PixelMap) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionIconUpdated-------'); }, // Listen for mission name changes. onMissionLabelUpdated: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionLabelUpdated-------'); }, // Listen for mission closure events. onMissionClosed: (mission: number) => { hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionClosed-------'); } }; ``` ```ts // 1. Register a mission change listener. this.listenerId = missionManager.on('mission', this.listener); this.getUIContext().getPromptAction().showToast({ message: 'register_success_toast' }); hilog.info(DOMAIN_NUMBER, TAG, `missionManager.on success, listenerId = ${this.listenerId}`); ``` ```ts // 2. Obtain the latest 20 missions in the system. missionManager.getMissionInfos('', 20, (error: BusinessError, missions: Array) => { if (error.code) { hilog.error(DOMAIN_NUMBER, TAG, `getMissionInfos is called, error code: ${error.code}, err msg: ${error.message}.`); return; } hilog.info(DOMAIN_NUMBER, TAG, `size = ${missions.length}.`); hilog.info(DOMAIN_NUMBER, TAG, `missions = ${JSON.stringify(missions)}.`); //Check whether the recent task list contains etsclock. for (let i = 0; i < missions.length; i++) { if (missions[i].want.bundleName === 'ohos.samples.etsclock') { this.getUIContext().getPromptAction().showToast({ message: 'obtain_success_toast' }); hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfos.find etsclock, missionId = ${missions[i].missionId}`); this.missionId = missions[i].missionId; return; } } this.getUIContext().getPromptAction().showToast({ message: 'obtain_failed_toast' }); }); ``` ```ts // 3. Obtain the detailed information about a mission. missionManager.getMissionInfo('', this.missionId).then((data: missionManager.MissionInfo) => { this.getUIContext().getPromptAction().showToast({ message: JSON.stringify(data.want.bundleName) }); hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfo successfully. Data: ${JSON.stringify(data)}`); }).catch((error: BusinessError) => { hilog.error(DOMAIN_NUMBER, TAG, `getMissionInfo failed. Cause: ${error.message}`); }); ``` ```ts // 4. Obtain the mission snapshot. missionManager.getMissionSnapShot('', this.missionId, (error: BusinessError, snapshot: missionManager.MissionSnapshot) => { if (error === null) { hilog.info(DOMAIN_NUMBER, TAG, `bundleName = ${snapshot.ability.bundleName}.`); this.getUIContext().getPromptAction().showToast({ message: 'obtain_snapshot_success_toast' }); } else { hilog.error(DOMAIN_NUMBER, TAG, `getMissionSnapShot is called, error code: ${error.code}, error msg: ${error.message}.`); } }); ``` ```ts // 5. Obtain the low-resolution mission snapshot. missionManager.getLowResolutionMissionSnapShot('', this.missionId, (error: BusinessError, snapshot: missionManager.MissionSnapshot) => { if (error === null) { hilog.info(DOMAIN_NUMBER, TAG, `bundleName = ${snapshot.ability.bundleName}.`); this.getUIContext().getPromptAction().showToast({ message: 'obtain_low_snapshot_success_toast' }); } else { hilog.error(DOMAIN_NUMBER, TAG, `getLowResolutionMissionSnapShot is called, error code: ${error.code}, error msg: ${error.message}.`); } }); ``` ```ts // 6-1. Lock the mission. missionManager.lockMission(this.missionId).then(() => { this.getUIContext().getPromptAction().showToast({ message: 'lock_success_toast' }); hilog.info(DOMAIN_NUMBER, TAG, 'lockMission is called '); }); ``` ```ts // 6-2. Unlock the mission. missionManager.unlockMission(this.missionId).then(() => { this.getUIContext().getPromptAction().showToast({ message: 'unlock_success_toast' }); hilog.info(DOMAIN_NUMBER, TAG, 'unlockMission is called '); }); ``` ```ts // 7. Switch the mission to the foreground. missionManager.moveMissionToFront(this.missionId).then(() => { hilog.info(DOMAIN_NUMBER, TAG, 'moveMissionToFront is called '); }); ``` ```ts // 8. Clear a single mission. missionManager.clearMission(this.missionId).then(() => { this.getUIContext().getPromptAction().showToast({ message: 'delete_success_toast' }); hilog.info(DOMAIN_NUMBER, TAG, 'clearMission is called '); }); ``` ```ts // 9. Clear all missions. missionManager.clearAllMissions().catch((err: BusinessError) => { hilog.error(DOMAIN_NUMBER, TAG, `${err.code}`); }); ``` ```ts // 10. Deregister the mission change listener. missionManager.off('mission', this.listenerId, (error: BusinessError) => { if (error === null) { this.getUIContext().getPromptAction().showToast({ message: 'unregister_success_toast' }); } hilog.info(DOMAIN_NUMBER, TAG, 'unregisterMissionListener'); }); ```