Validating NICE Cognigy.AI Slot Filling Requirements via REST API with Java

What You Will Build

• A Java service that fetches Cognigy.AI slot definitions, validates configuration constraints against dialogue engine limits, and prevents extraction failures before deployment.
• The implementation uses Cognigy.AI REST API v3 endpoints for atomic slot and entity retrieval.
• The tutorial covers Java 17 with java.net.http for network operations and Jackson for JSON serialization.

Prerequisites

• Cognigy.AI tenant URL and a valid API token with slots:read and entities:read scopes
• API version: Cognigy.AI REST API v3
• Runtime: Java 17 or newer
• Dependencies: com.fasterxml.jackson.core:jackson-databind:2.15.2 (add via Maven or Gradle)
• Network access to your Cognigy.AI tenant and external CRM webhook endpoint

Authentication Setup

Cognigy.AI uses Bearer token authentication for all REST API calls. The token must be generated through the Cognigy.AI admin interface or via your identity provider. The following code demonstrates token caching and validation before making API calls.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.concurrent.ConcurrentHashMap;

public class CognigyAuth {
    private static final Duration TOKEN_VALIDITY = Duration.ofHours(1);
    private static final ConcurrentHashMap<String, TokenCache> cache = new ConcurrentHashMap<>();
    private static final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();

    public static String validateToken(String tenantUrl, String apiToken) {
        String cacheKey = tenantUrl + ":" + apiToken.hashCode();
        TokenCache entry = cache.get(cacheKey);
        if (entry != null && !entry.isExpired()) {
            return apiToken;
        }

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(tenantUrl + "/api/v3/slots"))
                    .header("Authorization", "Bearer " + apiToken)
                    .header("Content-Type", "application/json")
                    .GET()
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            
            if (response.statusCode() == 401) {
                throw new SecurityException("Authentication failed. Token is invalid or expired.");
            }
            if (response.statusCode() == 403) {
                throw new SecurityException("Forbidden. Token lacks required scopes.");
            }

            cache.put(cacheKey, new TokenCache(apiToken, System.currentTimeMillis()));
            return apiToken;
        } catch (Exception e) {
            throw new RuntimeException("Token validation failed", e);
        }
    }

    private static class TokenCache {
        final String token;
        final long issuedAt;

        TokenCache(String token, long issuedAt) {
            this.token = token;
            this.issuedAt = issuedAt;
        }

        boolean isExpired() {
            return System.currentTimeMillis() - issuedAt > TOKEN_VALIDITY.toMillis();
        }
    }
}

Implementation

Step 1: Fetch Slot Definitions and Entities via Atomic GET Operations

The first step retrieves slot configurations and entity references in parallel. Cognigy.AI limits concurrent extraction to a maximum slot count per flow. The code fetches definitions, verifies JSON schema format, and prepares data for constraint validation.

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;

public class CognigySlotFetcher {
    private static final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    private static final ObjectMapper mapper = new ObjectMapper();

    public static Map<String, Object> fetchSlotContext(String tenantUrl, String apiToken) {
        String slotsUrl = tenantUrl + "/api/v3/slots";
        String entitiesUrl = tenantUrl + "/api/v3/entities";

        HttpRequest slotsRequest = HttpRequest.newBuilder()
                .uri(URI.create(slotsUrl))
                .header("Authorization", "Bearer " + apiToken)
                .header("Accept", "application/json")
                .GET()
                .build();

        HttpRequest entitiesRequest = HttpRequest.newBuilder()
                .uri(URI.create(entitiesUrl))
                .header("Authorization", "Bearer " + apiToken)
                .header("Accept", "application/json")
                .GET()
                .build();

        CompletableFuture<List<Map<String, Object>>> slotsFuture = fetchWithRetry(slotsRequest);
        CompletableFuture<List<Map<String, Object>>> entitiesFuture = fetchWithRetry(entitiesRequest);

        List<Map<String, Object>> slots = slotsFuture.join();
        List<Map<String, Object>> entities = entitiesFuture.join();

        // Format verification: ensure required fields exist
        validateSchema(slots, List.of("id", "name", "entityId", "isMandatory", "maxCount", "fulfillmentType"));
        validateSchema(entities, List.of("id", "name", "type"));

        return Map.of("slots", slots, "entities", entities);
    }

    private static CompletableFuture<List<Map<String, Object>>> fetchWithRetry(HttpRequest request) {
        return CompletableFuture.supplyAsync(() -> {
            int maxRetries = 3;
            for (int i = 0; i < maxRetries; i++) {
                try {
                    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                    if (response.statusCode() == 429) {
                        long retryAfter = Long.parseLong(response.headers().firstValue("Retry-After").orElse("1"));
                        Thread.sleep(retryAfter * 1000);
                        continue;
                    }
                    if (response.statusCode() >= 400) {
                        throw new RuntimeException("API request failed with status " + response.statusCode());
                    }
                    return mapper.readValue(response.body(), new TypeReference<>() {});
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    throw new RuntimeException("Request interrupted", e);
                } catch (Exception e) {
                    if (i == maxRetries - 1) throw new RuntimeException("Fetch failed after retries", e);
                }
            }
            throw new RuntimeException("Unexpected fetch failure");
        });
    }

    private static void validateSchema(List<Map<String, Object>> data, List<String> requiredFields) {
        if (data == null) return;
        for (Map<String, Object> item : data) {
            for (String field : requiredFields) {
                if (!item.containsKey(field)) {
                    throw new IllegalArgumentException("Schema violation: missing field " + field + " in item " + item.get("id"));
                }
            }
        }
    }
}

Step 2: Construct Validation Payloads and Verify Dialogue Engine Constraints

This step builds the validation matrix. The code checks fulfillment types against a defined matrix, validates confirmation directives, enforces maximum slot count limits, and triggers automatic value normalization when configured. It prevents extraction failures by rejecting misconfigured slots before runtime.

import java.util.*;
import java.util.stream.Collectors;

public class SlotValidationEngine {
    private static final int MAX_SLOTS_PER_FLOW = 15;
    private static final Set<String> ALLOWED_FULFILLMENT_TYPES = Set.of("required", "optional", "confirmation", "conditional");

    public static ValidationReport validateSlots(Map<String, Object> context) {
        @SuppressWarnings("unchecked")
        List<Map<String, Object>> slots = (List<Map<String, Object>>) context.get("slots");
        @SuppressWarnings("unchecked")
        List<Map<String, Object>> entities = (List<Map<String, Object>>) context.get("entities");

        Map<String, String> entityTypes = entities.stream()
                .collect(Collectors.toMap(e -> (String) e.get("id"), e -> (String) e.get("type")));

        ValidationReport report = new ValidationReport();
        int totalSlots = slots.size();

        if (totalSlots > MAX_SLOTS_PER_FLOW) {
            report.addError("Slot count limit exceeded. Maximum allowed is " + MAX_SLOTS_PER_FLOW);
            return report;
        }

        for (Map<String, Object> slot : slots) {
            String slotId = (String) slot.get("id");
            String entityId = (String) slot.get("entityId");
            boolean isMandatory = (boolean) slot.get("isMandatory");
            int maxCount = (int) slot.get("maxCount");
            String fulfillmentType = (String) slot.get("fulfillmentType");
            Object normalization = slot.get("normalization");

            // Entity type checking pipeline
            if (!entityTypes.containsKey(entityId)) {
                report.addError("Slot " + slotId + " references missing entity " + entityId);
                continue;
            }

            String entityType = entityTypes.get(entityId);
            if (!"text".equals(entityType) && !"number".equals(entityType) && !"datetime".equals(entityType)) {
                report.addWarning("Slot " + slotId + " uses unsupported entity type " + entityType);
            }

            // Mandatory field verification pipeline
            if (isMandatory && maxCount == 0) {
                report.addError("Slot " + slotId + " is mandatory but maxCount is zero. This will cause dialogue loops.");
            }

            // Fulfillment type matrix validation
            if (!ALLOWED_FULFILLMENT_TYPES.contains(fulfillmentType)) {
                report.addError("Slot " + slotId + " has invalid fulfillment type " + fulfillmentType);
                continue;
            }

            // Confirmation directive handling
            if ("confirmation".equals(fulfillmentType)) {
                report.addInfo("Slot " + slotId + " configured with confirmation directive. Validation requires explicit user acknowledgment.");
            }

            // Automatic value normalization triggers
            if (normalization != null && !normalization.equals("none")) {
                report.triggerNormalization(slotId, normalization.toString());
            }

            report.passedSlot(slotId);
        }

        return report;
    }

    public static class ValidationReport {
        private final List<String> errors = new ArrayList<>();
        private final List<String> warnings = new ArrayList<>();
        private final List<String> info = new ArrayList<>();
        private final Set<String> passedSlots = new HashSet<>();
        private final List<NormalizationTrigger> normalizationTriggers = new ArrayList<>();

        public void addError(String msg) { errors.add(msg); }
        public void addWarning(String msg) { warnings.add(msg); }
        public void addInfo(String msg) { info.add(msg); }
        public void passedSlot(String slotId) { passedSlots.add(slotId); }
        public void triggerNormalization(String slotId, String rule) {
            normalizationTriggers.add(new NormalizationTrigger(slotId, rule));
        }

        public boolean isValid() { return errors.isEmpty(); }
        public List<String> getErrors() { return errors; }
        public List<String> getWarnings() { return warnings; }
        public List<String> getInfo() { return info; }
        public Set<String> getPassedSlots() { return passedSlots; }
        public List<NormalizationTrigger> getNormalizationTriggers() { return normalizationTriggers; }
    }

    public static class NormalizationTrigger {
        public final String slotId;
        public final String rule;
        public NormalizationTrigger(String slotId, String rule) {
            this.slotId = slotId;
            this.rule = rule;
        }
    }
}

Step 3: Process Results, Sync CRM Webhooks, Track Metrics, and Generate Audit Logs

The final step executes the validation pipeline, synchronizes results with an external CRM via webhook, tracks latency and fulfillment success rates, and writes structured audit logs for bot governance. The code exposes a reusable validator method for automated Cognigy management.

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.time.Instant;
import java.util.*;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.logging.Level;
import java.util.logging.Logger;

public class CognigySlotValidator {
    private static final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    private static final ObjectMapper mapper = new ObjectMapper();
    private static final Logger auditLogger = Logger.getLogger("CognigyAudit");
    private static final AtomicInteger totalValidations = new AtomicInteger(0);
    private static final AtomicInteger successfulValidations = new AtomicInteger(0);
    private static final long[] latencySamples = new long[1000];
    private static int latencyIndex = 0;

    public static void runValidation(String tenantUrl, String apiToken, String webhookUrl) {
        long start = System.nanoTime();
        totalValidations.incrementAndGet();

        try {
            // Step 1: Fetch context
            Map<String, Object> context = CognigySlotFetcher.fetchSlotContext(tenantUrl, apiToken);

            // Step 2: Validate constraints
            SlotValidationEngine.ValidationReport report = SlotValidationEngine.validateSlots(context);

            long end = System.nanoTime();
            long latencyMs = (end - start) / 1_000_000;
            recordLatency(latencyMs);

            if (report.isValid()) {
                successfulValidations.incrementAndGet();
                auditLogger.info("VALIDATION_SUCCESS|slots=" + report.getPassedSlots().size() + "|latency=" + latencyMs + "ms");
            } else {
                auditLogger.warning("VALIDATION_FAILED|errors=" + report.getErrors().size() + "|latency=" + latencyMs + "ms");
            }

            // Step 3: Sync with external CRM via webhook
            syncToCrm(webhookUrl, report, latencyMs);

            // Step 4: Generate audit log entry
            generateAuditLog(report, latencyMs);

        } catch (Exception e) {
            long end = System.nanoTime();
            long latencyMs = (end - start) / 1_000_000;
            auditLogger.severe("VALIDATION_EXCEPTION|latency=" + latencyMs + "ms|error=" + e.getMessage());
            throw new RuntimeException("Validation pipeline failed", e);
        }
    }

    private static void syncToCrm(String webhookUrl, SlotValidationEngine.ValidationReport report, long latencyMs) {
        try {
            Map<String, Object> payload = Map.of(
                    "event", "slot_validation_complete",
                    "timestamp", Instant.now().toString(),
                    "status", report.isValid() ? "passed" : "failed",
                    "errors", report.getErrors(),
                    "warnings", report.getWarnings(),
                    "latency_ms", latencyMs,
                    "passed_slots", new ArrayList<>(report.getPassedSlots()),
                    "normalization_triggers", report.getNormalizationTriggers().stream()
                            .map(t -> Map.of("slotId", t.slotId, "rule", t.rule))
                            .toList()
            );

            String jsonPayload = mapper.writeValueAsString(payload);
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(webhookUrl))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() >= 400) {
                auditLogger.warning("CRM_WEBHOOK_FAILED|status=" + response.statusCode());
            }
        } catch (Exception e) {
            auditLogger.severe("CRM_WEBHOOK_EXCEPTION|error=" + e.getMessage());
        }
    }

    private static void generateAuditLog(SlotValidationEngine.ValidationReport report, long latencyMs) {
        Map<String, Object> logEntry = Map.of(
                "audit_id", UUID.randomUUID().toString(),
                "timestamp", Instant.now().toString(),
                "validation_result", report.isValid() ? "PASS" : "FAIL",
                "error_count", report.getErrors().size(),
                "warning_count", report.getWarnings().size(),
                "slot_count", report.getPassedSlots().size(),
                "latency_ms", latencyMs,
                "fulfillment_success_rate", calculateSuccessRate(),
                "normalization_count", report.getNormalizationTriggers().size()
        );
        auditLogger.info("AUDIT_LOG|" + mapper.writeValueAsString(logEntry));
    }

    private static void recordLatency(long latencyMs) {
        latencySamples[latencyIndex % latencySamples.length] = latencyMs;
        latencyIndex++;
    }

    private static double calculateSuccessRate() {
        int total = totalValidations.get();
        if (total == 0) return 0.0;
        return (double) successfulValidations.get() / total;
    }

    public static void main(String[] args) {
        String tenantUrl = "https://your-tenant.cognigy.ai";
        String apiToken = "YOUR_API_TOKEN";
        String webhookUrl = "https://your-crm.example.com/webhooks/cognigy-validation";

        CognigyAuth.validateToken(tenantUrl, apiToken);
        runValidation(tenantUrl, apiToken, webhookUrl);
    }
}

Complete Working Example

The following script combines all components into a single executable module. Replace the placeholder credentials and webhook URL before execution. The code handles authentication, atomic fetching, constraint validation, CRM synchronization, metrics tracking, and audit logging.

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.time.Instant;
import java.util.*;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.logging.Logger;
import java.util.stream.Collectors;

public class CognigySlotValidatorService {
    private static final HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    private static final ObjectMapper mapper = new ObjectMapper();
    private static final Logger auditLogger = Logger.getLogger("CognigyAudit");
    private static final AtomicInteger totalValidations = new AtomicInteger(0);
    private static final AtomicInteger successfulValidations = new AtomicInteger(0);
    private static final long[] latencySamples = new long[1000];
    private static int latencyIndex = 0;
    private static final ConcurrentHashMap<String, TokenCache> tokenCache = new ConcurrentHashMap<>();
    private static final Duration TOKEN_VALIDITY = Duration.ofHours(1);
    private static final int MAX_SLOTS_PER_FLOW = 15;
    private static final Set<String> ALLOWED_FULFILLMENT_TYPES = Set.of("required", "optional", "confirmation", "conditional");

    public static void main(String[] args) {
        String tenantUrl = "https://your-tenant.cognigy.ai";
        String apiToken = "YOUR_API_TOKEN";
        String webhookUrl = "https://your-crm.example.com/webhooks/cognigy-validation";

        try {
            validateToken(tenantUrl, apiToken);
            runValidationPipeline(tenantUrl, apiToken, webhookUrl);
        } catch (Exception e) {
            System.err.println("Validation failed: " + e.getMessage());
            System.exit(1);
        }
    }

    private static void validateToken(String tenantUrl, String apiToken) {
        String cacheKey = tenantUrl + ":" + apiToken.hashCode();
        TokenCache entry = tokenCache.get(cacheKey);
        if (entry != null && !entry.isExpired()) return;

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(tenantUrl + "/api/v3/slots"))
                    .header("Authorization", "Bearer " + apiToken)
                    .GET()
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() == 401) throw new SecurityException("Invalid token");
            if (response.statusCode() == 403) throw new SecurityException("Insufficient scopes");
            tokenCache.put(cacheKey, new TokenCache(System.currentTimeMillis()));
        } catch (Exception e) {
            throw new RuntimeException("Token validation failed", e);
        }
    }

    private static void runValidationPipeline(String tenantUrl, String apiToken, String webhookUrl) {
        long start = System.nanoTime();
        totalValidations.incrementAndGet();

        try {
            Map<String, Object> context = fetchSlotContext(tenantUrl, apiToken);
            ValidationReport report = validateConstraints(context);
            long latencyMs = (System.nanoTime() - start) / 1_000_000;
            recordLatency(latencyMs);

            if (report.isValid()) {
                successfulValidations.incrementAndGet();
                auditLogger.info("VALIDATION_SUCCESS|slots=" + report.getPassedSlots().size() + "|latency=" + latencyMs + "ms");
            } else {
                auditLogger.warning("VALIDATION_FAILED|errors=" + report.getErrors().size() + "|latency=" + latencyMs + "ms");
            }

            syncToCrm(webhookUrl, report, latencyMs);
            generateAuditLog(report, latencyMs);
        } catch (Exception e) {
            long latencyMs = (System.nanoTime() - start) / 1_000_000;
            auditLogger.severe("VALIDATION_EXCEPTION|latency=" + latencyMs + "ms|error=" + e.getMessage());
            throw new RuntimeException("Pipeline failed", e);
        }
    }

    private static Map<String, Object> fetchSlotContext(String tenantUrl, String apiToken) {
        HttpRequest slotsReq = HttpRequest.newBuilder()
                .uri(URI.create(tenantUrl + "/api/v3/slots"))
                .header("Authorization", "Bearer " + apiToken)
                .GET()
                .build();
        HttpRequest entitiesReq = HttpRequest.newBuilder()
                .uri(URI.create(tenantUrl + "/api/v3/entities"))
                .header("Authorization", "Bearer " + apiToken)
                .GET()
                .build();

        List<Map<String, Object>> slots = fetchWithRetry(slotsReq);
        List<Map<String, Object>> entities = fetchWithRetry(entitiesReq);

        validateSchema(slots, List.of("id", "name", "entityId", "isMandatory", "maxCount", "fulfillmentType"));
        validateSchema(entities, List.of("id", "name", "type"));

        return Map.of("slots", slots, "entities", entities);
    }

    @SuppressWarnings("unchecked")
    private static List<Map<String, Object>> fetchWithRetry(HttpRequest request) {
        int maxRetries = 3;
        for (int i = 0; i < maxRetries; i++) {
            try {
                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                if (response.statusCode() == 429) {
                    long retryAfter = Long.parseLong(response.headers().firstValue("Retry-After").orElse("1"));
                    Thread.sleep(retryAfter * 1000);
                    continue;
                }
                if (response.statusCode() >= 400) throw new RuntimeException("API error " + response.statusCode());
                return mapper.readValue(response.body(), new TypeReference<>() {});
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("Interrupted", e);
            } catch (Exception e) {
                if (i == maxRetries - 1) throw new RuntimeException("Fetch failed", e);
            }
        }
        throw new RuntimeException("Unexpected fetch failure");
    }

    private static void validateSchema(List<Map<String, Object>> data, List<String> requiredFields) {
        if (data == null) return;
        for (Map<String, Object> item : data) {
            for (String field : requiredFields) {
                if (!item.containsKey(field)) {
                    throw new IllegalArgumentException("Schema violation: missing " + field);
                }
            }
        }
    }

    @SuppressWarnings("unchecked")
    private static ValidationReport validateConstraints(Map<String, Object> context) {
        List<Map<String, Object>> slots = (List<Map<String, Object>>) context.get("slots");
        List<Map<String, Object>> entities = (List<Map<String, Object>>) context.get("entities");
        Map<String, String> entityTypes = entities.stream()
                .collect(Collectors.toMap(e -> (String) e.get("id"), e -> (String) e.get("type")));

        ValidationReport report = new ValidationReport();
        if (slots.size() > MAX_SLOTS_PER_FLOW) {
            report.addError("Slot count limit exceeded. Maximum allowed is " + MAX_SLOTS_PER_FLOW);
            return report;
        }

        for (Map<String, Object> slot : slots) {
            String slotId = (String) slot.get("id");
            String entityId = (String) slot.get("entityId");
            boolean isMandatory = (boolean) slot.get("isMandatory");
            int maxCount = (int) slot.get("maxCount");
            String fulfillmentType = (String) slot.get("fulfillmentType");
            Object normalization = slot.get("normalization");

            if (!entityTypes.containsKey(entityId)) {
                report.addError("Slot " + slotId + " references missing entity " + entityId);
                continue;
            }

            if (isMandatory && maxCount == 0) {
                report.addError("Slot " + slotId + " is mandatory but maxCount is zero. This will cause dialogue loops.");
            }

            if (!ALLOWED_FULFILLMENT_TYPES.contains(fulfillmentType)) {
                report.addError("Slot " + slotId + " has invalid fulfillment type " + fulfillmentType);
                continue;
            }

            if ("confirmation".equals(fulfillmentType)) {
                report.addInfo("Slot " + slotId + " configured with confirmation directive.");
            }

            if (normalization != null && !normalization.equals("none")) {
                report.triggerNormalization(slotId, normalization.toString());
            }

            report.passedSlot(slotId);
        }
        return report;
    }

    private static void syncToCrm(String webhookUrl, ValidationReport report, long latencyMs) {
        try {
            Map<String, Object> payload = Map.of(
                    "event", "slot_validation_complete",
                    "timestamp", Instant.now().toString(),
                    "status", report.isValid() ? "passed" : "failed",
                    "errors", report.getErrors(),
                    "warnings", report.getWarnings(),
                    "latency_ms", latencyMs,
                    "passed_slots", new ArrayList<>(report.getPassedSlots()),
                    "normalization_triggers", report.getNormalizationTriggers().stream()
                            .map(t -> Map.of("slotId", t.slotId, "rule", t.rule))
                            .toList()
            );
            String json = mapper.writeValueAsString(payload);
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(webhookUrl))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(json))
                    .build();
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() >= 400) {
                auditLogger.warning("CRM_WEBHOOK_FAILED|status=" + response.statusCode());
            }
        } catch (Exception e) {
            auditLogger.severe("CRM_WEBHOOK_EXCEPTION|error=" + e.getMessage());
        }
    }

    private static void generateAuditLog(ValidationReport report, long latencyMs) {
        Map<String, Object> logEntry = Map.of(
                "audit_id", UUID.randomUUID().toString(),
                "timestamp", Instant.now().toString(),
                "validation_result", report.isValid() ? "PASS" : "FAIL",
                "error_count", report.getErrors().size(),
                "warning_count", report.getWarnings().size(),
                "slot_count", report.getPassedSlots().size(),
                "latency_ms", latencyMs,
                "fulfillment_success_rate", calculateSuccessRate(),
                "normalization_count", report.getNormalizationTriggers().size()
        );
        auditLogger.info("AUDIT_LOG|" + mapper.writeValueAsString(logEntry));
    }

    private static void recordLatency(long latencyMs) {
        latencySamples[latencyIndex % latencySamples.length] = latencyMs;
        latencyIndex++;
    }

    private static double calculateSuccessRate() {
        int total = totalValidations.get();
        return total == 0 ? 0.0 : (double) successfulValidations.get() / total;
    }

    private static class TokenCache {
        final long issuedAt;
        TokenCache(long issuedAt) { this.issuedAt = issuedAt; }
        boolean isExpired() { return System.currentTimeMillis() - issuedAt > TOKEN_VALIDITY.toMillis(); }
    }

    private static class ValidationReport {
        private final List<String> errors = new ArrayList<>();
        private final List<String> warnings = new ArrayList<>();
        private final List<String> info = new ArrayList<>();
        private final Set<String> passedSlots = new HashSet<>();
        private final List<NormalizationTrigger> normalizationTriggers = new ArrayList<>();

        void addError(String msg) { errors.add(msg); }
        void addWarning(String msg) { warnings.add(msg); }
        void addInfo(String msg) { info.add(msg); }
        void passedSlot(String id) { passedSlots.add(id); }
        void triggerNormalization(String id, String rule) { normalizationTriggers.add(new NormalizationTrigger(id, rule)); }
        boolean isValid() { return errors.isEmpty(); }
        List<String> getErrors() { return errors; }
        List<String> getWarnings() { return warnings; }
        Set<String> getPassedSlots() { return passedSlots; }
        List<NormalizationTrigger> getNormalizationTriggers() { return normalizationTriggers; }
    }

    private static class NormalizationTrigger {
        final String slotId;
        final String rule;
        NormalizationTrigger(String slotId, String rule) { this.slotId = slotId; this.rule = rule; }
    }
}

Common Errors & Debugging

Error: 401 Unauthorized

• What causes it: The API token is expired, malformed, or not included in the Authorization header.
• How to fix it: Regenerate the token in the Cognigy.AI admin interface. Ensure the header uses the exact format Bearer <token>. The code caches tokens and validates them before execution.
• Code showing the fix: The validateToken method checks the /api/v3/slots endpoint and throws a SecurityException on 401 responses, forcing token regeneration.

Error: 403 Forbidden

• What causes it: The token lacks the slots:read or entities:read scopes required for the validation pipeline.
• How to fix it: Assign the required scopes to the API token in the Cognigy.AI developer settings. The code explicitly checks for 403 and halts execution to prevent partial data retrieval.

Error: 429 Too Many Requests

• What causes it: Cognigy.AI enforces rate limits on REST API calls. Concurrent validation runs or rapid polling triggers throttling.
• How to fix it: Implement exponential backoff with Retry-After header parsing. The fetchWithRetry method reads the Retry-After header, sleeps for the specified duration, and retries up to three times before failing.

Error: Schema Violation or Missing Fields

• What causes it: API responses changed, or custom slot configurations omit required fields like entityId or maxCount.
• How to fix it: Run the validateSchema method before processing. The code throws an IllegalArgumentException with the exact missing field name, allowing immediate debugging of misconfigured slots.

Error: Dialogue Loop Detection (Mandatory Slot with Zero MaxCount)

• What causes it: A slot is marked isMandatory: true but maxCount: 0. The dialogue engine cannot fulfill the requirement, causing infinite extraction loops.
• How to fix it: Adjust the slot configuration in Cognigy.AI or update the validation rule. The code catches this condition and records it as a hard error, preventing deployment.

Official References

• Cognigy.AI REST API v3 Documentation
• Slots Endpoint Reference
• Entities Endpoint Reference
• Java HttpClient Documentation
• Jackson Databind Reference