manageengine-mdm

ManageEngine MDM API Client

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.

Table of Contents

• 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

Installation

npm install manageengine-mdm

Quick Start

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();

Authentication

The client uses OAuth 2.0 for authentication. You can authenticate using either an authorization code flow or directly with a refresh token.

Token Storage

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.

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<void> {
    await this.redis.set(`mdm:token:${accountsServer}`, JSON.stringify(state));
  }

  async getToken(accountsServer: string): Promise<AuthState | undefined> {
    const token = await this.redis.get(`mdm:token:${accountsServer}`);
    return token ? JSON.parse(token) : undefined;
  }

  async clearToken(accountsServer: string): Promise<void> {
    await this.redis.del(`mdm:token:${accountsServer}`);
  }
}

// Example database implementation
class DatabaseTokenStorage implements TokenStorage {
  async saveToken(accountsServer: string, state: AuthState): Promise<void> {
    await db.tokens.upsert({
      accountsServer,
      state: JSON.stringify(state),
    });
  }

  async getToken(accountsServer: string): Promise<AuthState | undefined> {
    const record = await db.tokens.findOne({ accountsServer });
    return record ? JSON.parse(record.state) : undefined;
  }

  async clearToken(accountsServer: string): Promise<void> {
    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
});

Available Scopes

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',
}

API Reference

Device Management

List Devices

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

const device = await mdm.devices.getDevice(deviceId, summary);

Device Actions

// 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,
});

Compliance & Geofencing

The Compliance API allows you to create and manage geofencing profiles and compliance policies.

List Fence Profiles

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

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

const updated = await mdm.compliance.modifyFenceProfile(
  profileId,
  {
    policies: Array<Policy>;
    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

// 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;
}

Scheduled Actions

The Scheduled Actions API enables scheduling of device operations like restart and shutdown.

Create Schedule

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

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

const result = await mdm.scheduledActions.deleteSchedule({
  group_action_id: number;
  action_name: 'restart' | 'shutdown';
});

// Response type:
interface DeleteScheduleResponse {
  status: string;
}

Validate Schedule

const validation = await mdm.scheduledActions.validateSchedule({
  groups: string[];
  action_name: 'restart' | 'shutdown';
});

// Response type:
interface ValidateScheduleResponse {
  valid: boolean;
  invalid_groups?: string[];
  reason?: string;
}

VPP Management

The VPP API manages Volume Purchase Program accounts and tokens for iOS app distribution.

List VPP Accounts

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

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

// 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

// 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;
  }>;
}

Error Handling

The client provides typed error handling for various scenarios:

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);
  }
}

TypeScript Support

This library is written in TypeScript and provides comprehensive type definitions for all APIs. The types are automatically included when you install the package.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT