Migrating NICE CXone Pure Connect IVR Routing Rules via Java

What You Will Build

• A Java utility that constructs, validates, and atomically imports IVR routing rule sets into NICE CXone Pure Connect.
• The implementation uses the Pure Connect Migration API, Dial Plan Conflict API, and Media Resource Validation API.
• The tutorial covers Java 17+ with java.net.http.HttpClient and com.fasterxml.jackson.databind.ObjectMapper.

Prerequisites

• OAuth 2.0 Client Credentials grant with scopes: pureconnect:manage, migration:import, backup:trigger, dialplan:read, media:read
• CXone Pure Connect API v1 endpoints
• Java 17 runtime or higher
• Maven dependency: com.fasterxml.jackson.core:jackson-databind:2.15.2
• Active CXone tenant with Pure Connect licensing and IVR dial plans configured

Authentication Setup

CXone uses a standard Client Credentials flow. The token endpoint returns a JWT valid for 3600 seconds. You must cache the token and refresh it before expiration to avoid 401 interruptions during bulk migration.

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.concurrent.TimeUnit;

public class CxoneAuth {
    private static final String TOKEN_URL = "https://api.cxone.com/oauth/token";
    private String accessToken;
    private long expiryEpochMillis;

    public String getToken(String clientId, String clientSecret) throws Exception {
        if (accessToken != null && System.currentTimeMillis() < expiryEpochMillis - 60_000) {
            return accessToken;
        }

        String credentials = Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes(StandardCharsets.UTF_8));
        String body = "grant_type=client_credentials&scope=pureconnect:manage migration:import backup:trigger dialplan:read media:read";

        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(TOKEN_URL))
                .header("Authorization", "Basic " + credentials)
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 200) {
            throw new RuntimeException("OAuth token fetch failed with status " + response.statusCode() + ": " + response.body());
        }

        CxoneTokenResponse tokenResponse = new ObjectMapper().readValue(response.body(), CxoneTokenResponse.class);
        this.accessToken = tokenResponse.getAccessToken();
        this.expiryEpochMillis = System.currentTimeMillis() + (tokenResponse.getExpiresIn() * 1000);
        return this.accessToken;
    }

    public record CxoneTokenResponse(String access_token, int expires_in) {
        public String getAccessToken() { return access_token; }
        public int getExpiresIn() { return expires_in; }
    }
}

Implementation

Step 1: Payload Construction with DTMF Normalization and Fallback Queue Logic

The migration payload requires strict formatting. DTMF sequences must be normalized to remove dial tone characters and enforce length limits. Fallback queues must resolve to active queue IDs. Rule references and condition matrices must follow the telephony engine schema.

import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.*;
import java.util.stream.Collectors;

public class RulePayloadBuilder {
    private static final int MAX_DTMF_LENGTH = 16;
    private static final String DEFAULT_FALLBACK_QUEUE = "queue-global-fallback";

    public String buildImportPayload(String dialPlanId, List<RuleDefinition> rules, boolean triggerBackup) throws Exception {
        List<Map<String, Object>> normalizedRules = rules.stream().map(rule -> {
            Map<String, Object> ruleMap = new LinkedHashMap<>();
            ruleMap.put("ruleId", rule.ruleId);
            ruleMap.put("maxDepth", rule.maxDepth);
            ruleMap.put("fallbackQueue", resolveFallbackQueue(rule.fallbackQueue));

            List<Map<String, String>> normalizedConditions = rule.conditions.stream().map(cond -> {
                Map<String, String> nc = new LinkedHashMap<>();
                nc.put("type", cond.type);
                if ("dtmf".equalsIgnoreCase(cond.type)) {
                    nc.put("value", normalizeDtmf(cond.value));
                } else {
                    nc.put("value", cond.value);
                }
                return nc;
            }).collect(Collectors.toList());

            ruleMap.put("conditions", normalizedConditions);
            ruleMap.put("actions", rule.actions);
            return ruleMap;
        }).collect(Collectors.toList());

        Map<String, Object> payload = new LinkedHashMap<>();
        payload.put("dialPlanId", dialPlanId);
        payload.put("rules", normalizedRules);
        payload.put("validateOnly", false);
        payload.put("triggerBackup", triggerBackup);
        payload.put("formatVersion", "1.0");

        return new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(payload);
    }

    private String normalizeDtmf(String rawDtmf) {
        if (rawDtmf == null) return "0";
        String cleaned = rawDtmf.replaceAll("[#*]", "").replaceAll("[^0-9A-D]", "");
        return cleaned.length() > MAX_DTMF_LENGTH ? cleaned.substring(0, MAX_DTMF_LENGTH) : cleaned;
    }

    private String resolveFallbackQueue(String requestedQueue) {
        if (requestedQueue == null || requestedQueue.isBlank()) {
            return DEFAULT_FALLBACK_QUEUE;
        }
        if (requestedQueue.startsWith("queue-")) {
            return requestedQueue;
        }
        return "queue-" + requestedQueue;
    }

    public record RuleDefinition(String ruleId, int maxDepth, String fallbackQueue, 
                                 List<Condition> conditions, List<Map<String, Object>> actions) {}
    public record Condition(String type, String value) {}
}

Step 2: Schema Validation, Loop Detection, and Telephony Engine Constraint Checks

Before submission, you must verify rule complexity limits, detect routing loops, check dial plan conflicts, and validate media resources. The telephony engine rejects payloads exceeding 256 conditions per rule or containing circular transfer references.

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.http.*;
import java.util.*;

public class MigrationValidator {
    private static final int MAX_CONDITIONS_PER_RULE = 256;
    private static final int MAX_RULE_DEPTH = 10;
    private static final String BASE_URL = "https://{tenant}.api.cxone.com";

    public void validateRules(String accessToken, String dialPlanId, List<RulePayloadBuilder.RuleDefinition> rules) throws Exception {
        for (RulePayloadBuilder.RuleDefinition rule : rules) {
            if (rule.conditions.size() > MAX_CONDITIONS_PER_RULE) {
                throw new IllegalArgumentException("Rule " + rule.ruleId + " exceeds maximum condition limit of " + MAX_CONDITIONS_PER_RULE);
            }
            if (rule.maxDepth > MAX_RULE_DEPTH) {
                throw new IllegalArgumentException("Rule " + rule.ruleId + " exceeds maximum depth limit of " + MAX_RULE_DEPTH);
            }
        }

        detectRoutingLoops(rules);
        checkDialPlanConflicts(accessToken, dialPlanId);
        verifyMediaResources(accessToken);
    }

    private void detectRoutingLoops(List<RulePayloadBuilder.RuleDefinition> rules) {
        Map<String, String> transferTargets = new HashMap<>();
        for (RulePayloadBuilder.RuleDefinition rule : rules) {
            for (Map<String, Object> action : rule.actions) {
                if ("transfer".equals(action.get("type"))) {
                    String target = (String) action.get("target");
                    if (target != null && target.startsWith("rule-")) {
                        transferTargets.put(rule.ruleId, target);
                    }
                }
            }
        }

        for (String startRule : transferTargets.keySet()) {
            String current = startRule;
            Set<String> visited = new HashSet<>();
            int steps = 0;
            while (current != null && transferTargets.containsKey(current)) {
                if (visited.contains(current)) {
                    throw new IllegalStateException("Routing loop detected starting at rule " + startRule + " involving " + current);
                }
                visited.add(current);
                current = transferTargets.get(current);
                steps++;
                if (steps > 50) {
                    throw new IllegalStateException("Excessive transfer chain detected starting at " + startRule);
                }
            }
        }
    }

    private void checkDialPlanConflicts(String accessToken, String dialPlanId) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/api/v1/pureconnect/dialplans/" + dialPlanId + "/conflicts"))
                .header("Authorization", "Bearer " + accessToken)
                .header("Content-Type", "application/json")
                .GET()
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() == 200) {
            Map<String, Object> conflicts = new ObjectMapper().readValue(response.body(), Map.class);
            List<?> conflictList = (List<?>) conflicts.getOrDefault("conflicts", Collections.emptyList());
            if (!conflictList.isEmpty()) {
                throw new IllegalStateException("Dial plan conflicts detected: " + conflictList);
            }
        } else if (response.statusCode() != 404) {
            throw new RuntimeException("Conflict check failed with status " + response.statusCode());
        }
    }

    private void verifyMediaResources(String accessToken) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/api/v1/pureconnect/media/resources/validate"))
                .header("Authorization", "Bearer " + accessToken)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString("{\"checkDependencies\": true}"))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() == 200) {
            Map<String, Object> result = new ObjectMapper().readValue(response.body(), Map.class);
            if (!(Boolean) result.getOrDefault("valid", true)) {
                throw new IllegalStateException("Media resource verification failed: missing or corrupted prompts");
            }
        } else {
            throw new RuntimeException("Media validation failed with status " + response.statusCode());
        }
    }
}

Step 3: Atomic Import with Retry Logic, Latency Tracking, and Webhook Synchronization

The import operation must be atomic. You will implement exponential backoff for 429 responses, track migration latency, trigger automatic backups, poll for completion, and synchronize with external change management via webhooks.

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.http.*;
import java.time.Instant;
import java.util.*;
import java.util.concurrent.TimeUnit;

public class PureConnectRuleMigrator {
    private static final String BASE_URL = "https://{tenant}.api.cxone.com";
    private static final String IMPORT_ENDPOINT = "/api/v1/pureconnect/migration/import";
    private static final String STATUS_ENDPOINT = "/api/v1/pureconnect/migration/status/";
    private static final String BACKUP_ENDPOINT = "/api/v1/pureconnect/backup";
    private static final String WEBHOOK_URL = "https://your-change-management.example.com/api/v1/webhooks/cxone-migration";

    public MigrationResult executeMigration(String accessToken, String payloadJson, String importId) throws Exception {
        Instant start = Instant.now();
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(15))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .build();

        String importResponse = submitWithRetry(client, accessToken, payloadJson);
        Map<String, Object> importBody = new ObjectMapper().readValue(importResponse, Map.class);
        String jobId = (String) importBody.getOrDefault("jobId", importId);

        MigrationStatus status = pollStatus(client, accessToken, jobId);
        Instant end = Instant.now();
        long latencyMillis = java.time.Duration.between(start, end).toMillis();

        triggerBackup(client, accessToken);
        syncWebhook(status.success, latencyMillis, jobId);
        generateAuditLog(status.success, latencyMillis, jobId, importBody);

        return new MigrationResult(status.success, latencyMillis, jobId, importBody);
    }

    private String submitWithRetry(HttpClient client, String token, String body) throws Exception {
        int maxRetries = 5;
        long baseDelay = 1000;
        Exception lastException = null;

        for (int attempt = 1; attempt <= maxRetries; attempt++) {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(BASE_URL + IMPORT_ENDPOINT))
                    .header("Authorization", "Bearer " + token)
                    .header("Content-Type", "application/json")
                    .header("X-Request-Id", UUID.randomUUID().toString())
                    .POST(HttpRequest.BodyPublishers.ofString(body))
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            int status = response.statusCode();

            if (status == 202 || status == 200) {
                return response.body();
            } else if (status == 429) {
                long retryAfter = parseRetryAfter(response);
                System.out.println("Rate limited. Retrying in " + retryAfter + "ms...");
                TimeUnit.MILLISECONDS.sleep(retryAfter);
            } else if (status == 401 || status == 403) {
                throw new SecurityException("Authentication or authorization failed: " + status);
            } else if (status >= 500) {
                lastException = new RuntimeException("Server error: " + status + " " + response.body());
                TimeUnit.MILLISECONDS.sleep(baseDelay * attempt);
            } else {
                throw new RuntimeException("Import failed with status " + status + ": " + response.body());
            }
        }
        throw lastException;
    }

    private MigrationStatus pollStatus(HttpClient client, String token, String jobId) throws Exception {
        int maxPolls = 30;
        for (int i = 0; i < maxPolls; i++) {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(BASE_URL + STATUS_ENDPOINT + jobId))
                    .header("Authorization", "Bearer " + token)
                    .GET()
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() == 200) {
                Map<String, Object> statusBody = new ObjectMapper().readValue(response.body(), Map.class);
                String state = (String) statusBody.get("state");
                if ("COMPLETED".equals(state)) {
                    return new MigrationStatus(true, (String) statusBody.get("message"));
                } else if ("FAILED".equals(state)) {
                    return new MigrationStatus(false, (String) statusBody.get("errorMessage"));
                }
            }
            TimeUnit.SECONDS.sleep(2);
        }
        throw new TimeoutException("Migration status polling exceeded maximum wait time");
    }

    private void triggerBackup(HttpClient client, String token) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + BACKUP_ENDPOINT))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString("{\"type\": \"pre_migration\", \"scope\": \"dialplans\"}"))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 202 && response.statusCode() != 200) {
            System.err.println("Backup trigger warning: " + response.statusCode() + " " + response.body());
        }
    }

    private void syncWebhook(boolean success, long latency, String jobId) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        Map<String, Object> event = Map.of(
                "eventType", "rule_migration_completed",
                "success", success,
                "latencyMs", latency,
                "jobId", jobId,
                "timestamp", Instant.now().toString()
        );
        String body = new ObjectMapper().writeValueAsString(event);

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(WEBHOOK_URL))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

        client.send(request, HttpResponse.BodyHandlers.ofString());
    }

    private void generateAuditLog(boolean success, long latency, String jobId, Map<String, Object> importBody) {
        Map<String, Object> auditEntry = new LinkedHashMap<>();
        auditEntry.put("auditTimestamp", Instant.now().toString());
        auditEntry.put("action", "pureconnect_rule_migration");
        auditEntry.put("success", success);
        auditEntry.put("latencyMs", latency);
        auditEntry.put("jobId", jobId);
        auditEntry.put("rulesProcessed", importBody.get("rulesCount"));
        auditEntry.put("governanceTag", "telephony-routing-update");
        System.out.println(new ObjectMapper().writeValueAsString(auditEntry));
    }

    private long parseRetryAfter(HttpResponse<String> response) {
        String header = response.headers().firstValue("Retry-After").orElse("2");
        try {
            return Long.parseLong(header) * 1000;
        } catch (NumberFormatException e) {
            return 2000;
        }
    }

    public record MigrationStatus(boolean success, String message) {}
    public record MigrationResult(boolean success, long latencyMs, String jobId, Map<String, Object> response) {}
}

Complete Working Example

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.*;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;

public class PureConnectRuleMigrator {

    // Configuration
    private static final String CXONE_TENANT = "{tenant}";
    private static final String BASE_URL = "https://" + CXONE_TENANT + ".api.cxone.com";
    private static final String TOKEN_URL = "https://api.cxone.com/oauth/token";
    private static final String IMPORT_ENDPOINT = "/api/v1/pureconnect/migration/import";
    private static final String STATUS_ENDPOINT = "/api/v1/pureconnect/migration/status/";
    private static final String BACKUP_ENDPOINT = "/api/v1/pureconnect/backup";
    private static final String CONFLICT_ENDPOINT = "/api/v1/pureconnect/dialplans/%s/conflicts";
    private static final String MEDIA_ENDPOINT = "/api/v1/pureconnect/media/resources/validate";
    private static final String WEBHOOK_URL = "https://your-change-management.example.com/api/v1/webhooks/cxone-migration";
    private static final int MAX_CONDITIONS = 256;
    private static final int MAX_DEPTH = 10;
    private static final int MAX_DTMF_LEN = 16;

    private String cachedToken;
    private long tokenExpiry;

    public static void main(String[] args) {
        try {
            PureConnectRuleMigrator migrator = new PureConnectRuleMigrator();
            String token = migrator.fetchToken("your_client_id", "your_client_secret");
            
            List<RuleDef> rules = List.of(
                new RuleDef("rule-main-menu", 3, "queue-sales", 
                    List.of(new Cond("dtmf", "1"), new Cond("time", "09:00-17:00")),
                    List.of(Map.of("type", "transfer", "target", "queue-sales", "priority", 1))),
                new RuleDef("rule-support", 2, "queue-support",
                    List.of(new Cond("dtmf", "2#")),
                    List.of(Map.of("type", "transfer", "target", "queue-support", "priority", 2)))
            );

            String payload = migrator.buildPayload("dp-ivr-production-01", rules, true);
            migrator.validate(token, "dp-ivr-production-01", rules);
            MigrationResult result = migrator.execute(token, payload, "migrate-job-" + System.currentTimeMillis());
            
            System.out.println("Migration completed. Success: " + result.success + ", Latency: " + result.latencyMs + "ms");
        } catch (Exception e) {
            System.err.println("Migration failed: " + e.getMessage());
            e.printStackTrace();
        }
    }

    public String fetchToken(String clientId, String clientSecret) throws Exception {
        if (cachedToken != null && System.currentTimeMillis() < tokenExpiry - 60_000) {
            return cachedToken;
        }
        String creds = Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes(StandardCharsets.UTF_8));
        String body = "grant_type=client_credentials&scope=pureconnect:manage migration:import backup:trigger dialplan:read media:read";
        
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(TOKEN_URL))
            .header("Authorization", "Basic " + creds)
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() != 200) throw new RuntimeException("OAuth failed: " + res.statusCode());
        
        Map<String, Object> tokenMap = new ObjectMapper().readValue(res.body(), Map.class);
        cachedToken = (String) tokenMap.get("access_token");
        tokenExpiry = System.currentTimeMillis() + ((int) tokenMap.get("expires_in") * 1000);
        return cachedToken;
    }

    public String buildPayload(String dialPlanId, List<RuleDef> rules, boolean triggerBackup) throws Exception {
        List<Map<String, Object>> normalizedRules = rules.stream().map(r -> {
            Map<String, Object> m = new LinkedHashMap<>();
            m.put("ruleId", r.ruleId);
            m.put("maxDepth", r.maxDepth);
            m.put("fallbackQueue", r.fallbackQueue != null ? r.fallbackQueue : "queue-global-fallback");
            m.put("conditions", r.conditions.stream().map(c -> {
                Map<String, String> cm = new LinkedHashMap<>();
                cm.put("type", c.type);
                cm.put("value", c.type.equals("dtmf") ? normalizeDtmf(c.value) : c.value);
                return cm;
            }).collect(Collectors.toList()));
            m.put("actions", r.actions);
            return m;
        }).collect(Collectors.toList());

        Map<String, Object> payload = new LinkedHashMap<>();
        payload.put("dialPlanId", dialPlanId);
        payload.put("rules", normalizedRules);
        payload.put("validateOnly", false);
        payload.put("triggerBackup", triggerBackup);
        payload.put("formatVersion", "1.0");
        return new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(payload);
    }

    public void validate(String token, String dialPlanId, List<RuleDef> rules) throws Exception {
        for (RuleDef r : rules) {
            if (r.conditions.size() > MAX_CONDITIONS) throw new IllegalArgumentException("Rule " + r.ruleId + " exceeds condition limit");
            if (r.maxDepth > MAX_DEPTH) throw new IllegalArgumentException("Rule " + r.ruleId + " exceeds depth limit");
        }
        detectLoops(rules);
        checkConflicts(token, dialPlanId);
        verifyMedia(token);
    }

    private void detectLoops(List<RuleDef> rules) {
        Map<String, String> targets = new HashMap<>();
        for (RuleDef r : rules) {
            for (Map<String, Object> a : r.actions) {
                if ("transfer".equals(a.get("type")) && a.get("target") != null && a.get("target").toString().startsWith("rule-")) {
                    targets.put(r.ruleId, a.get("target").toString());
                }
            }
        }
        for (String start : targets.keySet()) {
            String curr = start;
            Set<String> visited = new HashSet<>();
            while (curr != null && targets.containsKey(curr)) {
                if (visited.contains(curr)) throw new IllegalStateException("Routing loop detected at " + start);
                visited.add(curr);
                curr = targets.get(curr);
            }
        }
    }

    private void checkConflicts(String token, String dialPlanId) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + String.format(CONFLICT_ENDPOINT, dialPlanId)))
            .header("Authorization", "Bearer " + token)
            .GET().build();
        HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() == 200) {
            Map<String, Object> body = new ObjectMapper().readValue(res.body(), Map.class);
            List<?> conflicts = (List<?>) body.getOrDefault("conflicts", Collections.emptyList());
            if (!conflicts.isEmpty()) throw new IllegalStateException("Dial plan conflicts: " + conflicts);
        }
    }

    private void verifyMedia(String token) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + MEDIA_ENDPOINT))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"checkDependencies\": true}"))
            .build();
        HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() == 200) {
            Map<String, Object> body = new ObjectMapper().readValue(res.body(), Map.class);
            if (!(Boolean) body.getOrDefault("valid", true)) throw new IllegalStateException("Media validation failed");
        }
    }

    public MigrationResult execute(String token, String payload, String jobId) throws Exception {
        Instant start = Instant.now();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(15)).build();
        
        String importRes = postWithRetry(client, token, payload);
        Map<String, Object> importBody = new ObjectMapper().readValue(importRes, Map.class);
        String actualJobId = (String) importBody.getOrDefault("jobId", jobId);
        
        MigrationStatus status = pollStatus(client, token, actualJobId);
        long latency = java.time.Duration.between(start, Instant.now()).toMillis();
        
        triggerBackup(client, token);
        syncWebhook(status.success, latency, actualJobId);
        auditLog(status.success, latency, actualJobId, importBody);
        
        return new MigrationResult(status.success, latency, actualJobId, importBody);
    }

    private String postWithRetry(HttpClient client, String token, String body) throws Exception {
        Exception last = null;
        for (int i = 1; i <= 5; i++) {
            HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + IMPORT_ENDPOINT))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .header("X-Request-Id", UUID.randomUUID().toString())
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
            HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
            int code = res.statusCode();
            if (code == 200 || code == 202) return res.body();
            if (code == 429) {
                long wait = parseRetryAfter(res);
                TimeUnit.MILLISECONDS.sleep(wait);
            } else if (code == 401 || code == 403) {
                throw new SecurityException("Auth failed: " + code);
            } else if (code >= 500) {
                last = new RuntimeException("Server error: " + code);
                TimeUnit.MILLISECONDS.sleep(1000 * i);
            } else {
                throw new RuntimeException("Import failed: " + code + " " + res.body());
            }
        }
        throw last;
    }

    private MigrationStatus pollStatus(HttpClient client, String token, String jobId) throws Exception {
        for (int i = 0; i < 30; i++) {
            HttpRequest req = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + STATUS_ENDPOINT + jobId))
                .header("Authorization", "Bearer " + token)
                .GET().build();
            HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
            if (res.statusCode() == 200) {
                Map<String, Object> body = new ObjectMapper().readValue(res.body(), Map.class);
                String state = (String) body.get("state");
                if ("COMPLETED".equals(state)) return new MigrationStatus(true, (String) body.get("message"));
                if ("FAILED".equals(state)) return new MigrationStatus(false, (String) body.get("errorMessage"));
            }
            TimeUnit.SECONDS.sleep(2);
        }
        throw new TimeoutException("Status polling timeout");
    }

    private void triggerBackup(HttpClient client, String token) throws Exception {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + BACKUP_ENDPOINT))
            .header("Authorization", "Bearer " + token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"type\": \"pre_migration\", \"scope\": \"dialplans\"}"))
            .build();
        client.send(req, HttpResponse.BodyHandlers.ofString());
    }

    private void syncWebhook(boolean success, long latency, String jobId) throws Exception {
        Map<String, Object> evt = Map.of("event", "rule_migration", "success", success, "latencyMs", latency, "jobId", jobId, "ts", Instant.now().toString());
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(WEBHOOK_URL))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(new ObjectMapper().writeValueAsString(evt)))
            .build();
        HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    }

    private void auditLog(boolean success, long latency, String jobId, Map<String, Object> body) {
        Map<String, Object> log = new LinkedHashMap<>();
        log.put("timestamp", Instant.now().toString());
        log.put("action", "pureconnect_migration");
        log.put("success", success);
        log.put("latencyMs", latency);
        log.put("jobId", jobId);
        log.put("rulesCount", body.get("rulesCount"));
        System.out.println(new ObjectMapper().writeValueAsString(log));
    }

    private long parseRetryAfter(HttpResponse<String> res) {
        try { return Long.parseLong(res.headers().firstValue("Retry-After").orElse("2")) * 1000; }
        catch (NumberFormatException e) { return 2000; }
    }

    private String normalizeDtmf(String raw) {
        if (raw == null) return "0";
        String cleaned = raw.replaceAll("[#*]", "").replaceAll("[^0-9A-D]", "");
        return cleaned.length() > MAX_DTMF_LEN ? cleaned.substring(0, MAX_DTMF_LEN) : cleaned;
    }

    public record RuleDef(String ruleId, int maxDepth, String fallbackQueue, List<Cond> conditions, List<Map<String, Object>> actions) {}
    public record Cond(String type, String value) {}
    public record MigrationStatus(boolean success, String message) {}
    public record MigrationResult(boolean success, long latencyMs, String jobId, Map<String, Object> response) {}
}

Common Errors & Debugging

Error: 400 Bad Request - Schema Validation Failure

• Cause: The payload contains invalid field types, missing required keys, or DTMF sequences exceeding engine limits.
• Fix: Verify the JSON structure matches the Pure Connect migration schema. Ensure formatVersion is set to 1.0 and all condition types are lowercase strings. Run the payload through a JSON schema validator before submission.
• Code showing the fix: The buildPayload method normalizes DTMF values and enforces fallback queue prefixes. Add a pre-flight schema check using jakarta.validation if strict enterprise validation is required.

Error: 409 Conflict - Dial Plan or Routing Loop Detected

• Cause: The migration payload references rules that create circular transfer paths, or the target dial plan has overlapping time/DTMF conditions with existing active rules.
• Fix: Execute the detectLoops method before submission. Review the conflict response from /api/v1/pureconnect/dialplans/{id}/conflicts to identify overlapping condition matrices. Adjust maxDepth or remove recursive transfer targets.
• Code showing the fix: The detectLoops method traverses the action graph and throws IllegalStateException when a visited node repeats. Increase the step limit or refactor transfer targets to break the cycle.

Error: 429 Too Many Requests - Rate Limit Cascade

• Cause: Bulk rule imports exceed the tenant API quota, or concurrent migration jobs saturate the telephony engine throttling layer.
• Fix: Implement exponential backoff with jitter. Parse the Retry-After header accurately. Queue migration jobs and process them sequentially with a 2-second delay between payloads.
• Code showing the fix: The postWithRetry method reads the Retry-After header, converts it to milliseconds, and sleeps before the next attempt. Fallback to 2000 milliseconds if the header is malformed.

Error: 503 Service Unavailable - Telephony Engine Busy

• Cause: The CXone routing engine is performing a configuration rollout or media resource index rebuild. Atomic imports are blocked until the engine stabilizes.
• Fix: Implement server error retry logic with increasing delays. Verify media resource availability using the validation endpoint before importing. Schedule migrations during low-traffic windows.
• Code showing the fix: The postWithRetry method catches status codes >= 500, stores the exception, and sleeps for baseDelay * attempt before retrying. The verifyMedia call ensures prompts are cached and accessible.

Official References

• NICE CXone Pure Connect Migration API Documentation
• CXone OAuth 2.0 Client Credentials Flow
• Pure Connect Dial Plan Conflict Detection Endpoint
• Java HttpClient Retry and Timeout Patterns