A TypeScript wrapper for the ManageEngine Mobile Device Manager Plus API
npm install manageengine-mdm[![npm package][npm-img]][npm-url]
[![Build Status][build-img]][build-url]
[![Downloads][downloads-img]][downloads-url]
[![Issues][issues-img]][issues-url]
[![Code Coverage][codecov-img]][codecov-url]
[![Commitizen Friendly][commitizen-img]][commitizen-url]
[![Semantic Release][semantic-release-img]][semantic-release-url]
A comprehensive TypeScript client for the ManageEngine Mobile Device Manager Plus API. This client provides type-safe access to MDM functionality including device management, app distribution, compliance policies, and more.
- Installation
- Quick Start
- Authentication
- Token Storage
- Available Scopes
- API Reference
- Device Management
- Group Management
- Profile Management
- App Management
- Compliance & Geofencing
- Scheduled Actions
- VPP Management
- Content Management
- User Management
- Enrollment Settings
- Announcements
- Blocklist Management
- Error Handling
- TypeScript Support
- Contributing
- License
``bash`
npm install manageengine-mdm
`typescript
import { ManageEngineMDM, Scope } from 'manageengine-mdm';
// Initialize the client
const mdm = new ManageEngineMDM({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
baseUrl: 'https://mdm.manageengine.com',
redirectUri: 'https://your-app.com/oauth/callback',
scope: [Scope.DEVICE_MGMT_READ, Scope.DEVICE_MGMT_UPDATE],
});
// Get authorization URL
const authUrl = mdm.getAuthorizationUrl('offline', 'consent');
// Initialize with authorization code
await mdm.initialize(code, accountsServer);
// Or initialize with refresh token
await mdm.initializeWithRefreshToken(refreshToken, accountsServer);
// Check authentication status
const isAuthenticated = await mdm.isAuthenticated();
// Get current auth state
const authState = await mdm.getAuthState();
// Clear auth state when needed
await mdm.clearAuthState();
`
The client uses OAuth 2.0 for authentication. You can authenticate using either an authorization code flow or directly with a refresh token.
By default, tokens are stored in memory, but you can provide a custom token storage implementation to persist tokens in Redis, a database, or any other storage system.
`typescript
import { TokenStorage, AuthState } from 'manageengine-mdm';
// Example Redis implementation
class RedisTokenStorage implements TokenStorage {
private readonly redis: Redis;
constructor(redis: Redis) {
this.redis = redis;
}
async saveToken(accountsServer: string, state: AuthState): Promise
await this.redis.set(mdm:token:${accountsServer}, JSON.stringify(state));
}
async getToken(accountsServer: string): Promise
const token = await this.redis.get(mdm:token:${accountsServer});
return token ? JSON.parse(token) : undefined;
}
async clearToken(accountsServer: string): Promise
await this.redis.del(mdm:token:${accountsServer});
}
}
// Example database implementation
class DatabaseTokenStorage implements TokenStorage {
async saveToken(accountsServer: string, state: AuthState): Promise
await db.tokens.upsert({
accountsServer,
state: JSON.stringify(state),
});
}
async getToken(accountsServer: string): Promise
const record = await db.tokens.findOne({ accountsServer });
return record ? JSON.parse(record.state) : undefined;
}
async clearToken(accountsServer: string): Promise
await db.tokens.delete({ accountsServer });
}
}
// Use custom storage when initializing the client
const mdm = new ManageEngineMDM({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
baseUrl: 'https://mdm.manageengine.com',
redirectUri: 'https://your-app.com/oauth/callback',
scope: [Scope.DEVICE_MGMT_READ],
tokenStorage: new RedisTokenStorage(redisClient), // Your custom storage
});
`
`typescript
enum Scope {
// Inventory Management
INVENTORY_CREATE = 'MDMOnDemand.MDMInventory.CREATE',
INVENTORY_UPDATE = 'MDMOnDemand.MDMInventory.UPDATE',
INVENTORY_READ = 'MDMOnDemand.MDMInventory.READ',
INVENTORY_DELETE = 'MDMOnDemand.MDMInventory.DELETE',
INVENTORY_ALL = 'MDMOnDemand.MDMInventory.ALL',
// Device Management
DEVICE_MGMT_CREATE = 'MDMOnDemand.MDMDeviceMgmt.CREATE',
DEVICE_MGMT_UPDATE = 'MDMOnDemand.MDMDeviceMgmt.UPDATE',
DEVICE_MGMT_READ = 'MDMOnDemand.MDMDeviceMgmt.READ',
DEVICE_MGMT_DELETE = 'MDMOnDemand.MDMDeviceMgmt.DELETE',
DEVICE_MGMT_ALL = 'MDMOnDemand.MDMDeviceMgmt.ALL',
// User Management
USER_CREATE = 'MDMOnDemand.MDMUser.CREATE',
USER_UPDATE = 'MDMOnDemand.MDMUser.UPDATE',
USER_READ = 'MDMOnDemand.MDMUser.READ',
USER_DELETE = 'MDMOnDemand.MDMUser.DELETE',
USER_ALL = 'MDMOnDemand.MDMUser.ALL',
}
`
#### List Devices
`typescript`
const devices = await mdm.devices.listDevices({
search?: string;
platform?: ('iOS' | 'Android' | 'Windows')[];
exclude_removed?: boolean;
imei?: number;
owned_by?: 'Corporate' | 'Personal';
device_type?: ('smartphone' | 'Tablet' | 'Laptop' | 'Desktop' | 'Tv')[];
serial_number?: string;
email?: string;
});
#### Get Device Details
`typescript`
const device = await mdm.devices.getDevice(deviceId, summary);
#### Device Actions
`typescript
// Lock device
await mdm.devices.performAction(deviceId, 'lock', {
lock_message: 'Device locked for security',
});
// Wipe device
await mdm.devices.performAction(deviceId, 'complete_wipe', {
wipe_sd_card: true,
});
`
The Compliance API allows you to create and manage geofencing profiles and compliance policies.
#### List Fence Profiles
`typescript
const profiles = await mdm.compliance.listFenceProfiles();
// Response type:
interface CompliancePoliciesResponse {
compliance_policies: Array<{
compliance_id: number;
compliance_name: string;
platform_type: number;
created_by: number;
creation_time: number;
last_modified_time: number;
compliant_devices_count: number;
non_compliant_devices_count: number;
}>;
}
`
#### Create Fence Profile
`typescript
const profile = await mdm.compliance.addFenceProfile({
policies: [{
rule: {
rule_name: string;
rule_criterions: Array<{
rule_criteria_type: number;
geo_fence_id: number;
rule_criteria_state: number;
}>;
evaluation_order: number;
},
action: {
action_attributes: Array<{
execution_order: number;
action_attribute_type: number;
lock_message?: string;
unlock_pin?: string;
is_remote_alarm: boolean;
is_mark_as_non_compliant: boolean;
alert_email_ids?: Array<{
email: string;
user_name: string;
}>;
}>;
}
}],
description: string;
compliance_name: string;
});
// Response type:
interface ComplianceCreateResponse {
collection_id: number;
is_moved_to_trash: boolean;
compliance_id: number;
}
`
#### Modify Fence Profile
`typescript
const updated = await mdm.compliance.modifyFenceProfile(
profileId,
{
policies: Array
description: string;
compliance_name: string;
}
);
// Response type:
interface ComplianceUpdateResponse {
collection_id: number;
user_id: number;
compliance_file_name_path: string;
remove_compliance_file_name_path: string;
customer_id: number;
compliance_id: number;
compliance_name: string;
}
`
#### Group Management
`typescript
// Get associated groups
const groups = await mdm.compliance.getFenceGroups(complianceId);
// Response type:
interface ComplianceGroupListResponse {
group_list: Array<{
group_id: number;
group_name: string;
group_type: number;
member_count: number;
}>;
compliance_id: number;
}
// Associate with groups
await mdm.compliance.associateMultipleGroups(complianceId, {
group_ids: string[];
});
// Get group devices
const devices = await mdm.compliance.getGroupDevices(complianceId, groupId);
// Response type:
interface ComplianceGroupDetailsResponse {
group_id: number;
group_name: string;
devices: Array<{
device_id: number;
device_name: string;
device_platform: number;
device_compliance_state: string;
compliance_score: number;
}>;
group_compliance_state: string;
compliance_id: number;
compliance_name: string;
}
`
The Scheduled Actions API enables scheduling of device operations like restart and shutdown.
#### Create Schedule
`typescript
const schedule = await mdm.scheduledActions.createSchedule({
groups: string[]; // Group IDs
time_zone: string; // Timezone for scheduling
schedule_params: {
schedule_type: string; // Schedule type
monthly_perform?: string;
daily_time?: string;
monthly_week_day?: number;
days_of_week?: string;
daily_interval_type?: string;
scheduler_disabled?: boolean;
monthly_time?: number;
monthly_week_num?: number;
weekly_time?: number;
monthly_day?: number;
months_list?: string;
};
reason_message: string;
execution_type: number; // 1 = Once, 2 = Repeat
expiry: number; // Expiry timestamp
schedule_once_time: number; // Execution timestamp
action_name: 'restart' | 'shutdown';
});
// Response type:
interface CreateScheduleResponse {
group_action_id: number;
status: string;
}
`
#### Modify Schedule
`typescript
const result = await mdm.scheduledActions.modifySchedule({
group_action_id: number; // ID of schedule to modify
// ... same parameters as createSchedule
});
// Response type:
interface ModifyScheduleResponse {
status: string;
}
`
#### Delete Schedule
`typescript
const result = await mdm.scheduledActions.deleteSchedule({
group_action_id: number;
action_name: 'restart' | 'shutdown';
});
// Response type:
interface DeleteScheduleResponse {
status: string;
}
`
#### Validate Schedule
`typescript
const validation = await mdm.scheduledActions.validateSchedule({
groups: string[];
action_name: 'restart' | 'shutdown';
});
// Response type:
interface ValidateScheduleResponse {
valid: boolean;
invalid_groups?: string[];
reason?: string;
}
`
The VPP API manages Volume Purchase Program accounts and tokens for iOS app distribution.
#### List VPP Accounts
`typescript
const accounts = await mdm.vpp.getAllVppAccounts();
// Response type:
interface VppAccountResponse {
non_vpp_app_count: number;
vpp_token_details: Array<{
businessstore_id: number;
organisation_name: string;
license_assign_type: number;
location_name: string;
}>;
trash_count: number;
}
`
#### Add VPP Account
`typescript
const account = await mdm.vpp.addVppAccount({
vpp_token_file: number; // File ID of server token
email_address: string; // Notification email
});
// Response type:
interface AddVppAccountResponse {
location_name: string;
expired: boolean;
businessstore_id: number;
organisation_name: string;
expiry_date: number;
}
`
#### VPP Account Operations
`typescript
// Get account details
const details = await mdm.vpp.getVppAccount(vppId);
// Response type:
interface VppAccountDetail {
non_vpp_apps_count: number;
location_name: string;
total_apps_count: number;
expiry_date: number;
last_sync_time: number;
org_type: number;
organization_name: string;
businessstore_id: number;
license_assign_type: number;
}
// Modify account
await mdm.vpp.modifyVppAccount(vppId, {
vpp_token_file: number;
email_address: string;
});
// Remove account
await mdm.vpp.removeVppAccount(vppId);
`
#### VPP Sync Operations
`typescript
// Get sync status
const status = await mdm.vpp.getVppSyncStatus(vppId);
// Response type:
interface VppSyncStatusResponse {
if_license_insufficient: boolean;
if_sync_failed: boolean;
apps_with_insufficient_licenses: number;
failed_apps_count: number;
total_apps_count: number;
successful_apps_count: number;
last_sync_time: number;
completed_apps_count: number;
remarks: string | null;
status: number;
other_mdm_hostname: string;
}
// Sync account
await mdm.vpp.syncVppAccount(vppId, {
remove_from_other_mdm: boolean;
});
// Get failure details
const failures = await mdm.vpp.getVppFailureDetails(vppId);
// Response type:
interface VppFailureResponse {
apps: Array<{
appgroupid: number;
appname: string;
displayimageloc: string;
licensecount: number;
packageid: number;
resourcecount: number;
}>;
}
`
The client provides typed error handling for various scenarios:
`typescript``
try {
await mdm.devices.getDevice(deviceId);
} catch (error) {
if (error instanceof MDMAuthenticationError) {
// Handle authentication failure
console.log('Authentication failed:', error.message);
} else if (error instanceof MDMRequestError) {
// Handle API request error
console.log('API error:', error.statusCode, error.message);
} else {
// Handle other errors
console.error('Unexpected error:', error);
}
}
This library is written in TypeScript and provides comprehensive type definitions for all APIs. The types are automatically included when you install the package.
We welcome contributions! Please see our Contributing Guide for details.
MIT
[build-img]: https://github.com/dovid-moshe-crow/manageengine-mdm/actions/workflows/release.yml/badge.svg
[build-url]: https://github.com/dovid-moshe-crow/manageengine-mdm/actions/workflows/release.yml
[downloads-img]: https://img.shields.io/npm/dt/manageengine-mdm
[downloads-url]: https://www.npmtrends.com/manageengine-mdm
[npm-img]: https://img.shields.io/npm/v/manageengine-mdm
[npm-url]: https://www.npmjs.com/package/manageengine-mdm
[issues-img]: https://img.shields.io/github/issues/dovid-moshe-crow/manageengine-mdm
[issues-url]: https://github.com/dovid-moshe-crow/manageengine-mdm/issues
[codecov-img]: https://codecov.io/gh/dovid-moshe-crow/manageengine-mdm/branch/main/graph/badge.svg
[codecov-url]: https://codecov.io/gh/dovid-moshe-crow/manageengine-mdm
[semantic-release-img]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-release-url]: https://github.com/semantic-release/semantic-release
[commitizen-img]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
[commitizen-url]: http://commitizen.github.io/cz-cli/