Mindtickle upgrade migration

MindTickle Upgrade & Migration

Overview

MindTickle is a sales enablement and readiness platform with APIs for managing courses, quizzes, user progress, and coaching sessions. The API exposes endpoints for content management, learner analytics, and CRM integration. Tracking API changes is essential because MindTickle evolves its content schema (course structures, quiz question types, scoring rubrics), user progress tracking fields, and SSO/SCIM provisioning models — breaking integrations that sync training completion data to Salesforce or automate onboarding workflows.

Version Detection

const MINDTICKLE_BASE = "https://api.mindtickle.com/v2";

async function detectMindTickleVersion(apiKey: string): Promise<void> {
  const res = await fetch(`${MINDTICKLE_BASE}/users`, {
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  });
  const version = res.headers.get("x-mt-api-version") ?? "v2";
  console.log(`MindTickle API version: ${version}`);

  // Check for deprecated course fields
  const coursesRes = await fetch(`${MINDTICKLE_BASE}/courses?limit=1`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await coursesRes.json();
  const knownFields = ["id", "title", "modules", "status", "created_at", "assigned_users"];
  if (data.courses?.[0]) {
    const actual = Object.keys(data.courses[0]);
    const newFields = actual.filter((f) => !knownFields.includes(f));
    if (newFields.length) console.log(`New course fields: ${newFields.join(", ")}`);
  }
}

Migration Checklist

• Review MindTickle release notes for API schema changes
• Audit codebase for hardcoded course status enums (draft, published, archived)
• Verify quiz question type support — new types may require parser updates
• Check user progress response for new completion metric fields
• Update SCIM provisioning payload if user attribute schema changed
• Test coaching session API for new rubric scoring fields
• Validate CRM sync field mappings (Salesforce/HubSpot) after API update
• Check if module ordering mechanism changed (position vs. sort_order)
• Update webhook handlers for course completion and quiz score events
• Run learner analytics export to verify report format compatibility

Schema Migration

// MindTickle course progress: flat completion → structured module-level tracking
interface OldProgress {
  user_id: string;
  course_id: string;
  completed: boolean;
  score: number;
  completed_at?: string;
}

interface NewProgress {
  user_id: string;
  course_id: string;
  status: "not_started" | "in_progress" | "completed" | "expired";
  overall_score: number;
  modules: Array<{
    module_id: string;
    status: string;
    score: number;
    attempts: number;
    time_spent_seconds: number;
  }>;
  certifications: Array<{ cert_id: string; issued_at: string; expires_at?: string }>;
  completed_at?: string;
}

function migrateProgress(old: OldProgress): NewProgress {
  return {
    user_id: old.user_id,
    course_id: old.course_id,
    status: old.completed ? "completed" : "not_started",
    overall_score: old.score,
    modules: [],
    certifications: [],
    completed_at: old.completed_at,
  };
}

Rollback Strategy

class MindTickleClient {
  private apiVersion: "v1" | "v2";

  constructor(private apiKey: string, version: "v1" | "v2" = "v2") {
    this.apiVersion = version;
  }

  async getCourses(limit = 50): Promise<any> {
    try {
      const res = await fetch(`https://api.mindtickle.com/${this.apiVersion}/courses?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`MindTickle ${res.status}`);
      return await res.json();
    } catch (err) {
      if (this.apiVersion === "v2") {
        console.warn("Falling back to MindTickle API v1");
        this.apiVersion = "v1";
        return this.getCourses(limit);
      }
      throw err;
    }
  }
}

Error Handling

Migration Issue	Symptom	Fix
Course status enum expanded	400 creating course with unrecognized status value	Fetch valid statuses from /courses/statuses endpoint
Quiz question type unsupported	Quiz import fails with unknown_question_type	Add parser support for new question types (drag-drop, hotspot)
SCIM attribute renamed	User provisioning fails with invalid attribute	Update SCIM payload to match current user schema from /schemas
Progress field restructured	Code crashes accessing progress.completed (now progress.status)	Update to check status === "completed" instead of boolean
Webhook signature algorithm changed	Webhook verification fails on all events	Update HMAC verification to use new algorithm from MindTickle docs

Resources

• MindTickle Integrations
• MindTickle API Documentation

Next Steps

For CI pipeline integration, see mindtickle-ci-integration.