1# @ohos.enterprise.systemManager (System Management)
2
3The **systemManager** module provides system management capabilities.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10>
11> The APIs of this module can be called only by a [device administrator application](../../mdm/mdm-kit-guide.md#introduction) that is enabled.
12
13## Modules to Import
14
15```ts
16import { systemManager } from '@kit.MDMKit';
17```
18
19## systemManager.setNTPServer
20
21setNTPServer(admin: Want, server: string): void
22
23Sets the NTP server information through the specified device administrator application.
24
25**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
26
27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
28
29**Parameters**
30
31| Name  | Type                                 | Mandatory  | Description     |
32| ----- | ----------------------------------- | ---- | ------- |
33| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes   | Device administrator application.|
34| server | string | Yes| NTP server addresses separated by a comma (,). For example, **ntpserver1.com,ntpserver2.com**.|
35
36**Error codes**
37
38For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
39
40| ID| Error Message                                                                     |
41| ------- | ---------------------------------------------------------------------------- |
42| 9200001 | The application is not an administrator application of the device. |
43| 9200002 | The administrator application does not have permission to manage the device. |
44| 201 | Permission verification failed. The application does not have the permission required to call the API. |
45| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
46
47**Example**
48
49```ts
50import { systemManager } from '@kit.MDMKit';
51import { Want } from '@kit.AbilityKit';
52let wantTemp: Want = {
53  bundleName: 'com.example.myapplication',
54  abilityName: 'EntryAbility',
55};
56let server: string = "ntpserver.com";
57try {
58  systemManager.setNTPServer(wantTemp, server);
59  console.info('Succeeded in setting NTPserver.');
60} catch (err) {
61  console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`);
62}
63```
64
65## systemManager.getNTPServer
66
67getNTPServer(admin: Want): string
68
69Obtains the NTP server information through the specified device administrator application.
70
71**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
72
73**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
74
75**Parameters**
76
77| Name| Type                               | Mandatory| Description          |
78| ------ | ----------------------------------- | ---- | -------------- |
79| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.|
80
81**Return value**
82
83| Type  | Description                           |
84| ------ | ------------------------------- |
85| string | NTP server information obtained.|
86
87**Error codes**
88
89For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
90
91| ID| Error Message                                                    |
92| -------- | ------------------------------------------------------------ |
93| 9200001  | The application is not an administrator application of the device. |
94| 9200002  | The administrator application does not have permission to manage the device. |
95| 201      | Permission verification failed. The application does not have the permission required to call the API. |
96| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
97
98**Example**
99
100```ts
101import { systemManager } from '@kit.MDMKit';
102import { Want } from '@kit.AbilityKit';
103import { BusinessError } from '@ohos.base';
104let wantTemp: Want = {
105  bundleName: 'com.example.myapplication',
106  abilityName: 'EntryAbility',
107};
108try {
109  systemManager.getNTPServer(wantTemp);
110  console.info('Succeeded in getting NTP server.');
111} catch (err) {
112  console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`);
113}
114```
115
116## systemManager.setOtaUpdatePolicy
117
118setOtaUpdatePolicy(admin: Want, policy: OtaUpdatePolicy): void
119
120Sets the over-the-air (OTA) update policy through the specified device administrator application. In intranet updates, call [systemManager.notifyUpdatePackages](#systemmanagernotifyupdatepackages) to notify the system of the update packages and then call this API to set the upgrade policy.
121
122**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
123
124**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
125
126**Parameters**
127
128| Name  | Type                                 | Mandatory  | Description     |
129| ----- | ----------------------------------- | ---- | ------- |
130| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes   | Device administrator application.|
131| policy | [OtaUpdatePolicy](#otaupdatepolicy) | Yes| OTA update policy to set.|
132
133**Error codes**
134
135For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
136
137| ID| Error Message                                                                     |
138| ------- | ---------------------------------------------------------------------------- |
139| 9200001 | The application is not an administrator application of the device.                       |
140| 9200002 | The administrator application does not have permission to manage the device. |
141| 201 | Permission verification failed. The application does not have the permission required to call the API. |
142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
143
144**Example**
145
146```ts
147import { systemManager } from '@kit.MDMKit';
148import { Want } from '@kit.AbilityKit';
149let wantTemp: Want = {
150  bundleName: 'com.example.myapplication',
151  abilityName: 'EntryAbility',
152};
153// Default update policy.
154let otaUpdatePolicy1: systemManager.OtaUpdatePolicy = {
155  "policyType": systemManager.PolicyType.DEFAULT,
156  "version": "version_1.0.0.0",
157};
158try {
159  systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy1);
160  console.info('Succeeded in setting ota update policy.');
161} catch (err) {
162  console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`);
163}
164// Prohibit update.
165let otaUpdatePolicy2: systemManager.OtaUpdatePolicy = {
166  "policyType": systemManager.PolicyType.PROHIBIT,
167  "version": "version_1.0.0.1",
168};
169try {
170  systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy2);
171  console.info('Succeeded in setting ota update policy.');
172} catch (err) {
173  console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`);
174}
175// Enforce update.
176let otaUpdatePolicy3: systemManager.OtaUpdatePolicy = {
177  "policyType": systemManager.PolicyType.UPDATE_TO_SPECIFIC_VERSION,
178  "version": "version_1.0.0.2",
179  "latestUpdateTime": 1716343200, // Timestamp
180};
181try {
182  systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy3);
183  console.info('Succeeded in setting ota update policy.');
184} catch (err) {
185  console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`);
186}
187// Update at the specified time period.
188let otaUpdatePolicy4: systemManager.OtaUpdatePolicy = {
189  "policyType": systemManager.PolicyType.WINDOWS,
190  "version": "version_1.0.0.3",
191  "installStartTime": 1716281049, // Timestamp
192  "installEndTime": 1716343200, // Timestamp
193};
194try {
195  systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy4);
196  console.info('Succeeded in setting ota update policy.');
197} catch (err) {
198  console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`);
199}
200// Delay the update.
201let otaUpdatePolicy5: systemManager.OtaUpdatePolicy = {
202  "policyType": systemManager.PolicyType.POSTPONE,
203  "version": "version_1.0.0.4",
204  "delayUpdateTime": 5, // Time for which the update is delayed, in hours.
205};
206try {
207  systemManager.setOtaUpdatePolicy(wantTemp, otaUpdatePolicy5);
208  console.info('Succeeded in setting ota update policy.');
209} catch (err) {
210  console.error(`Failed to set ota update policy. Code is ${err.code}, message is ${err.message}`);
211}
212
213```
214
215## systemManager.getOtaUpdatePolicy
216
217getOtaUpdatePolicy(admin: Want): OtaUpdatePolicy
218
219Obtains the OTA update policy through the specified device administrator application.
220
221**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
222
223**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
224
225**Parameters**
226
227| Name| Type                               | Mandatory| Description          |
228| ------ | ----------------------------------- | ---- | -------------- |
229| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.|
230
231**Return value**
232
233| Type  | Description                           |
234| ------ | ------------------------------- |
235| [OtaUpdatePolicy](#otaupdatepolicy) | **OtaUpdatePolicy** object containing the update policy obtained.|
236
237**Error codes**
238
239For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
240
241| ID| Error Message                                                    |
242| -------- | ------------------------------------------------------------ |
243| 9200001  | The application is not an administrator application of the device.       |
244| 9200002  | The administrator application does not have permission to manage the device. |
245| 201 | Permission verification failed. The application does not have the permission required to call the API. |
246| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
247
248**Example**
249
250```ts
251import { systemManager } from '@kit.MDMKit';
252import { Want } from '@kit.AbilityKit';
253let wantTemp: Want = {
254  bundleName: 'com.example.myapplication',
255  abilityName: 'EntryAbility',
256};
257try {
258  let policy: systemManager.OtaUpdatePolicy= systemManager.getOtaUpdatePolicy(wantTemp);
259  console.info(`Succeeded in getting update policy: ${JSON.stringify(policy)}`);
260} catch (err) {
261  console.error(`Failed to get update policy. Code is ${err.code}, message is ${err.message}`);
262}
263```
264
265## systemManager.notifyUpdatePackages
266
267notifyUpdatePackages(admin: Want, packageInfo: UpdatePackageInfo): Promise<void>
268
269Notifies the system of the update packages. In intranet updates, call this API to notify the system of the update packages, and then call [systemManager.setOtaUpdatePolicy](#systemmanagersetotaupdatepolicy) to set the update policy.
270
271**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
272
273**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
274
275**Parameters**
276
277| Name| Type                               | Mandatory| Description          |
278| ------ | ----------------------------------- | ---- | -------------- |
279| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.|
280| packageInfo  | [UpdatePackageInfo](#updatepackageinfo) | Yes  | Information about the system update packages.|
281
282**Return value**
283
284| Type                  | Description                     |
285| --------------------- | ------------------------- |
286| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.|
287
288**Error codes**
289
290For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
291
292| ID| Error Message                                                    |
293| -------- | ------------------------------------------------------------ |
294| 9200001  | The application is not an administrator application of the device.       |
295| 9200002  | The administrator application does not have permission to manage the device. |
296| 9201004  | The update packages do not exist or analyzing failed. |
297| 201 | Permission verification failed. The application does not have the permission required to call the API. |
298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
299
300**Example**
301
302```ts
303import { systemManager } from '@kit.MDMKit';
304import { BusinessError } from '@kit.BasicServicesKit';
305import { Want } from '@kit.AbilityKit';
306let wantTemp: Want = {
307  bundleName: 'com.example.myapplication',
308  abilityName: 'EntryAbility',
309};
310let notify: systemManager.NotifyDescription = {
311  "installTips": "installTips",
312  "installTipsDetail": "installTips detail"
313}
314let description: systemManager.PackageDescription = {
315  "notify": notify,
316}
317let updatePackages: Array<systemManager.Package> = [{
318  "type": systemManager.PackageType.FIRMWARE,
319  "path": "path",
320  "fd": 60,
321}]
322let updatePackageInfo: systemManager.UpdatePackageInfo = {
323  "version" : "1.0",
324  "packages" : updatePackages,
325  "description" : description,
326};
327systemManager.notifyUpdatePackages(wantTemp, updatePackageInfo).then(() => {
328  console.info('Succeeded in notifying update packages.');
329}).catch ((error: BusinessError) => {
330  console.error(`Failed to notify update packages. Code is ${error.code},message is ${error.message}`);
331});
332```
333
334## systemManager.getUpdateResult
335
336getUpdateResult(admin: Want, version: string): Promise&lt;UpdateResult&gt;
337
338Obtains the system update result.
339
340**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SYSTEM
341
342**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
343
344**Parameters**
345
346| Name| Type                               | Mandatory| Description          |
347| ------ | ----------------------------------- | ---- | -------------- |
348| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Device administrator application.|
349| version  | string | Yes  | Version of the update package.|
350
351**Return value**
352
353| Type                  | Description                     |
354| --------------------- | ------------------------- |
355| Promise&lt;[UpdateResult](#updateresult)&gt; | Promise used to return the system update result.|
356
357**Error codes**
358
359For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md).
360
361| ID| Error Message                                                    |
362| -------- | ------------------------------------------------------------ |
363| 9200001  | The application is not an administrator application of the device.       |
364| 9200002  | The administrator application does not have permission to manage the device. |
365| 201 | Permission verification failed. The application does not have the permission required to call the API. |
366| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.|
367
368**Example**
369
370```ts
371import { systemManager } from '@kit.MDMKit';
372import { BusinessError } from '@kit.BasicServicesKit';
373import { Want } from '@kit.AbilityKit';
374let wantTemp: Want = {
375  bundleName: 'com.example.myapplication',
376  abilityName: 'EntryAbility',
377};
378systemManager.getUpdateResult(wantTemp, "1.0").then((result:systemManager.UpdateResult) => {
379    console.info(`Succeeded in getting update result: ${JSON.stringify(result)}`);
380  }).catch((error: BusinessError) => {
381    console.error(`Get update result failed. Code is ${error.code},message is ${error.message}`);
382  });
383```
384
385## SystemUpdateInfo
386
387Represents information about the system version to update.
388
389**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
390
391| Name               | Type    | Mandatory | Description           |
392| ----------------- | ------ | --- | ------------- |
393| versionName       | string | Yes  | System version to update.  |
394| firstReceivedTime | number | Yes  | Time when the system update package is received for the first time.|
395| packageType       | string | Yes  | Type of the system update package to update. |
396
397## OtaUpdatePolicy
398
399Represents an OTA update policy.
400
401**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
402
403| Name        | Type    | Mandatory| Description                           |
404| ----------- | --------| ---- | ------------------------------- |
405| policyType        | [PolicyType](#policytype)   | Yes  | Type of the update policy.|
406| version | string   | Yes  | Version of the software to update.|
407| latestUpdateTime        | number   | No  | Latest update time (timestamp).|
408| delayUpdateTime | number   | No  | Period for which the update is postponed, in hours.|
409| installStartTime        | number   | No  | Start time (timestamp) of the installation window.|
410| installEndTime | number   | No  | End time (timestamp) of the installation window.|
411
412## PolicyType
413
414Enumerates the update policy types.
415
416**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
417
418| Name               | Value | Description   |
419| ----------------- | ---- | ----- |
420| DEFAULT | 0 | Default update policy, which periodically notifies the user of the update and starts the update after user confirmation.|
421| PROHIBIT  | 1 | Prohibit updates.|
422| UPDATE_TO_SPECIFIC_VERSION | 2 | Enforce updates. In this case, **latestUpdateTime** must be specified.|
423| WINDOWS | 3 | Update at the specified time window. In this case, **installStartTime** and **installEndTime** must be specified.|
424| POSTPONE | 4 | Postpone updates. After the time specified by **delayUpdateTime** is over, the default update policy is used.|
425
426## UpdatePackageInfo
427
428Represents information about the system update packages.
429
430**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
431
432| Name               | Type    | Mandatory | Description           |
433| ----------------- | ------ | --- | ------------- |
434| version       | string | Yes  | Version of the system update package.  |
435| packages | Array&lt;[Package](#package)&gt; | Yes  | Details about the system update packages.|
436| description       | [PackageDescription](#packagedescription) | No  | Description of the system update packages. |
437
438## Package
439
440Represents the details about a system update package.
441
442**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
443
444| Name               | Type    | Mandatory | Description           |
445| ----------------- | ------ | --- | ------------- |
446| type       | [PackageType](#packagetype) | Yes  | Type of the system update package.  |
447| path | string | Yes  | Path of the system update package. If **fd** is specified, pass in the update package name here.|
448| fd       | number | No  | File descriptor (FD) of the system update package. Currently, you cannot pass in **path** only. The **fd** parameter must also be passed in. |
449
450## PackageDescription
451
452Represents the description of a system update package.
453
454**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
455
456| Name               | Type    | Mandatory | Description           |
457| ----------------- | ------ | --- | ------------- |
458| notify       | [NotifyDescription](#notifydescription) | No  | Update notification defined by an enterprise.  |
459
460## NotifyDescription
461
462Represents the update notification defined by an enterprise.
463
464**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
465
466| Name               | Type    | Mandatory | Description           |
467| ----------------- | ------ | --- | ------------- |
468| installTips       | string | No  | Update tips provided by the enterprise.  |
469| installTipsDetail       | string | No  | Details about the update tips customized by the enterprise.  |
470
471## UpdateResult
472
473Represents the update result information.
474
475**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
476
477| Name               | Type  | Readable | Writable  | Description           |
478| ----------------- | ------ | ------ | ------ | ------------- |
479| version       | string |  Yes| No|Current version of the system.  |
480| status       | [UpdateStatus](#updatestatus) | Yes| No| System update status.  |
481| errorInfo       | [ErrorInfo](#errorinfo) | Yes| No| Error information.  |
482
483## ErrorInfo
484
485Represents the update error information.
486
487**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
488
489| Name               | Type    | Readable | Writable| Description           |
490| ----------------- | ------ | ------ | ------ | ------------- |
491| code       | number | Yes| No| Error code.  |
492| message       | string | Yes| No| Error message.  |
493
494## PackageType
495
496Enumerates the update package types.
497
498**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
499
500| Name               | Value | Description   |
501| ----------------- | ---- | ----- |
502| FIRMWARE | 1 | Firmware.|
503
504## UpdateStatus
505
506Enumerates the system update statuses.
507
508**System capability**: SystemCapability.Customization.EnterpriseDeviceManager
509
510| Name              | Value | Description   |
511| -----------------  | ---- | ----- |
512| NO_UPDATE_PACKAGE  | -4 | The system update package of the specified version does not exist.|
513| UPDATE_WAITING     | -3 | The system update package is waiting to be installed.|
514| UPDATING           | -2 | The system update is being performed.|
515| UPDATE_FAILURE     | -1 | The update failed.|
516| UPDATE_SUCCESS     | 0 | The update is successful.|
517