Migration Guide

1. Assessment Phase

• Current Architecture: Document existing licensing integration points
• License Models: Identify current restriction types (named user, concurrent, node-locked)
• Feature Control: Catalog how features are currently enabled/disabled
• Customer Data: Inventory existing customer licenses and entitlements
• Integration Points: Map CRM, billing, and support system integrations
• Usage Patterns: Analyze current usage metrics and peak loads
• Dependencies: Identify systems that depend on current licensing

2. elm Product Configuration

• Product Type: Choose Desktop, Server, or Web API based on deployment model
• Restriction Mapping: Map existing license types to elm restriction models
• Feature Migration: Define features and components in elm portal
• RSA Key Generation: Generate public/private key pairs for signature verification
• Test Environment: Set up staging environment for testing
• License Templates: Create license templates matching current offerings

3. SDK Integration

• Code Integration: Replace existing licensing SDK calls with elm SDK
• State Management: Implement elm state persistence patterns
• Error Handling: Update error handling for elm-specific scenarios
• Testing: Comprehensive testing with various license scenarios
• Backwards Compatibility: Plan transition period for existing customers
• Performance Testing: Validate performance with elm integration

Changes in current releases

• Unlimited entitlements: the .NET, Java, JavaScript, Python and Ruby SDKs now handle licenses and component entitlements with unlimited counts correctly. Update if you issue unlimited licenses.
• Expired sessions (.NET, Java): set ControlStrategy.StartSessionForExpiredSession = true to end an expired session and start a new one automatically on the next validation (default false).
• UTF-8: .NET, Java and C++ send UTF-8, so user names and license data with non-ASCII characters round-trip correctly.
• .NET: set ConnectionSettings.Log (Action<Exception, string>) to log HTTPS and RSA errors. The package assemblies, including the licensing model and hardware-info DLLs, are now signed. The obsolete UserControlManager.CheckoutFullLicenseAsync and UserControlManager.RegisterOfflineAsync were removed (Feb 2025); use CheckOutFullLicenseAsync / RegisterOfflineAsync on ServerControlManager or ControlManager.
• Python: the released SDK covers desktop licensing (ControlManager) and calls v3.2 endpoints.
• Ruby: SDK for Ruby/Rails web apps (Ruby 3.1+): server instance registration, per-user sessions, components and grace periods.
• Server-side entitlement check: a server acting for a desktop client can ask what that client's session is entitled to with the access-token endpoint POST /api/session_entitlements (session_validate scope). It is read-only and does not extend the session.

1. Data Export and Analysis

Extract customer license data from your existing system:

// Example: Export existing license data
public class LicenseExporter {
    public List<LegacyLicense> ExportLicenses() {
        var licenses = new List<LegacyLicense>();
        
        // Extract from your existing system
        foreach (var customer in GetAllCustomers()) {
            var license = new LegacyLicense {
                LicenseId = customer.LicenseId,
                CustomerId = customer.Id,
                CustomerName = customer.Name,
                Email = customer.Email,
                ProductName = customer.ProductName,
                LicenseType = customer.LicenseType, // Named, Concurrent, etc.
                UserLimit = customer.UserLimit,
                ExpirationDate = customer.ExpirationDate,
                EnabledFeatures = customer.Features.ToList(),
                HardwareId = customer.HardwareId,
                ActivationDate = customer.ActivationDate,
                IsActive = customer.IsActive
            };
            licenses.Add(license);
        }
        
        return licenses;
    }
}

2. License Mapping and Conversion

Map each legacy license onto the request body of the elm create_license action. elm has four license types and five commercial models, addressed by numeric id:

// Example: map a legacy license to an elm create_license request body
public class LicenseMapper {
    private const string ElmProductName = "My Product"; // product NAME as shown in the portal

    public object MapToElm(LegacyLicense legacy) {
        return new {
            license = new {
                product = ElmProductName,
                company_name = legacy.CustomerName,   // or company_id / crm_id to attach
                company_email = legacy.Email,         // to an existing company
                crm_id = legacy.CustomerId,
                license_type_id = MapLicenseType(legacy.LicenseType),
                commercial_model_id = legacy.ExpirationDate.HasValue ? 2 /* SaaS */ : 1 /* Perpetual */,
                features = MapFeatures(legacy.EnabledFeatures),
                description = $"Migrated from legacy license {legacy.LicenseId}"
            },
            entitlement = new { seat_count = legacy.UserLimit },
            term = new {
                start_date = legacy.ActivationDate.ToString("yyyy-MM-dd"),
                end_date = legacy.ExpirationDate?.ToString("yyyy-MM-dd")
            },
            comment = "Legacy license migration"
        };
    }

    private int MapLicenseType(string legacyType) {
        return legacyType.ToLower() switch {
            "named" => 1,       // Named User
            "concurrent" => 2,  // Concurrent
            "unlimited" => 3,   // Unrestricted
            "site" => 4,        // Node Locked (per machine)
            _ => 1
        };
    }

    private List<string> MapFeatures(List<string> legacyFeatures) {
        // Map legacy feature names to the feature names defined in the elm portal
        return legacyFeatures.Select(f => f switch {
            "advanced_reporting" => "AdvancedReporting",
            "api_access" => "APIAccess",
            _ => f
        }).ToList();
    }
}

3. Bulk License Creation

Create licenses through the elm license-administration API. Requests are authenticated with a personal access token (PAT) created in the elm portal, sent as Authorization: Bearer <token>. A token with the license_admin scope applies changes immediately; with only license_maintainer, actions are queued for approval in the portal. elm does not ship a client library for this API; the example below calls it with HttpClient.

// Example: bulk license migration through the elm PAT API
public class BulkMigration {
    private readonly HttpClient http = new HttpClient {
        BaseAddress = new Uri("https://elm.evoleap.com/")
    };

    public BulkMigration(string personalAccessToken) {
        http.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", personalAccessToken);
    }

    public async Task<MigrationResult> MigrateLicensesAsync(List<LegacyLicense> legacyLicenses) {
        var results = new MigrationResult();
        var mapper = new LicenseMapper();

        foreach (var legacy in legacyLicenses) {
            var response = await http.PostAsJsonAsync(
                "api/license_actions/create_license", mapper.MapToElm(legacy));
            var body = await response.Content.ReadFromJsonAsync<JsonElement>();

            if (!response.IsSuccessStatusCode) {
                results.FailedMigrations.Add(new MigrationFailure {
                    CustomerId = legacy.CustomerId,
                    Error = body.ToString(),
                    LegacyLicense = legacy
                });
                continue;
            }

            var licenseKey = body.GetProperty("license_key").GetString();

            // PREVIEW (API v3.5, not yet released): also store the legacy id as a
            // license property so clients receive it as custom_data. Replaces all properties.
            // await http.PostAsJsonAsync("api/license_actions/set_license_properties", new {
            //     license_key = licenseKey,
            //     properties = new[] { new { key = "legacy_license_id", value = legacy.LicenseId } }
            // });

            results.SuccessfulMigrations.Add(new MigrationMapping {
                CustomerId = legacy.CustomerId,
                CustomerEmail = legacy.Email,
                OldLicenseId = legacy.LicenseId,
                NewLicenseKey = licenseKey
            });
            await UpdateCustomerDatabase(legacy.CustomerId, licenseKey);
        }

        return results;
    }
}

Other actions on the same API include modify_license, modify_entitlement, create_term, add_feature, create_component_entitlement, deactivate_license and activate_license (all POST /api/license_actions/<action>, addressed by license_key). Read-only endpoints include GET /api/licenses, GET /api/licenses/show?license_key= and GET /api/users.

Usage History and Analytics

Consider what historical data to preserve:

• License Activation History: When customers first activated licenses
• Usage Patterns: Historical usage data for analytics
• Support History: Previous license-related support cases
• Billing Records: Payment and renewal history
• User Assignments: Historical user-to-license mappings

Rollback Planning

Always have a rollback plan in case of issues:

• Feature Flags: Ability to instantly revert to legacy system
• Data Backup: Complete backup of legacy license data
• Parallel Operation: Keep legacy system running during transition
• Customer Communication: Clear communication about any issues
• Support Escalation: Direct escalation path to elm support team

Success Metrics

Define clear metrics to measure migration success:

• Technical Metrics: System uptime, API response times, error rates
• Customer Metrics: Customer satisfaction, support ticket volume
• Business Metrics: License utilization, revenue impact, operational costs
• Operational Metrics: Migration velocity, rollback incidents, team productivity

Factors That May Extend Timeline

• Complex Legacy System: Heavily customized licensing may require additional mapping
• Large Customer Base: More customers mean more migration coordination
• Multiple Products: Each product may need separate migration planning
• Extensive Integrations: CRM, billing, and support system integrations take time
• Custom Requirements: Special customer needs may require custom development
• Regulatory Compliance: Some industries have specific licensing audit requirements

Factors That May Accelerate Timeline

• Simple Legacy System: Basic licensing models migrate quickly
• Cloud-Native Applications: Already cloud-ready applications integrate faster
• Professional Services: elm migration consultants can accelerate the process
• Staged Rollout: Phased approach allows parallel development and migration
• Modern SDK Usage: Applications already using modern patterns integrate more easily

Support Options

• Consulting Services: Guidance on migration planning, product configuration and license mapping
• Technical Support: Help with SDK integration and migration-related issues
• Staging Accounts: A free account on the elm staging server (elm-staging.evoleap.com) for testing your integration and migration scripts
• Documentation: This site, plus the README and samples shipped with each SDK

Getting Started with Migration Support

• Contact evoleap to discuss your migration needs
• Schedule a discovery call to assess your current licensing setup
• Get a staging account and develop a migration plan with evoleap
• Prepare your team with the integration guides on this site

Contact Information

• Email: info@evoleap.com
• Phone: +1 (832) 371-6677

See also evoleap support and contact options.