Upgrade Migration for MindTickle. Trigger: "mindtickle upgrade migration".
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.
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(", ")}`);
}
}
draft, published, archived)// 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,
};
}
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;
}
}
}
| 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 |
For CI pipeline integration, see mindtickle-ci-integration.