# Video Production Plan ### About this export | Field | Value | | --- | --- | | **content_type** | course | | **platform** | contentstack-academy | | **source_url** | https://www.contentstack.com/academy/courses/video-production-plan | | **language** | en | | **product_area** | Contentstack Academy | | **learning_path** | standalone | | **course_id** | video-production-plan | | **slug** | video-production-plan | | **version** | 2026-08-24 | | **last_updated** | 2026-08-26 | | **status** | published | | **keywords** | ["Contentstack Academy"] | | **summary_one_line** | Video Production Plan on Contentstack Academy. | | **total_duration_minutes** | 1 | | **lessons_count** | 28 | | **video_lessons_count** | 0 | | **text_lessons_count** | 28 | | **linked_learning_path** | standalone | | **linked_assessment_ref** | LMS_UNCONFIGURED_COURSE_ASSESSMENT | | **markdown_file_url** | /academy/md/courses/video-production-plan.md | | **generated_at** | 2026-08-26T11:17:48.094Z | | **intended_audience** | [] | | **prerequisites** | [] | | **related_courses** | [] | > **Academy MD v3** — companion `.md` for Ask AI. Quizzes and graded assessments are **LMS-only**; this file never contains answer keys. ## Course Overview | Metadata | Value | | --- | --- | | Catalog duration | — | | Released (if known) | 2026-08-24 | | Product area | Contentstack Academy | ### Learning objectives 1. Follow each lesson in order. 2. Practice in a training stack using placeholders **YOUR_STACK_API_KEY** and **YOUR_DELIVERY_TOKEN** in local `.env` files only. 3. Validate API responses against the official documentation. ### Topics covered Contentstack Academy ## Course structure ```text video-production-plan/ ├── 01-video-production-plan-overview · text · 3 min ├── 02-video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call · text · 3 min ├── 03-video-production-plan-video-2-headless-foundations-and-designing-for-editors · text · 3 min ├── 04-video-production-plan-video-3-structured-content-and-api-contracts · text · 3 min ├── 05-video-production-plan-video-4-composition-query-performance-and-modeling-in-practice · text · 3 min ├── 06-video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice · text · 3 min ├── 07-video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk · text · 3 min ├── 08-video-production-plan-video-7-performance-images-environments-and-cli-migrations · text · 3 min ├── 09-video-production-plan-video-8-live-preview-architecture-and-preview-routing · text · 3 min ├── 10-video-production-plan-video-9-visual-builder-releases-and-future-state-preview · text · 3 min ├── 11-video-production-plan-video-10-workflow-automation-hub-and-branch-strategy · text · 3 min ├── 12-video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks · text · 3 min ├── 13-video-production-plan-video-12-maintainability-governance-and-long-term-ownership · text · 3 min ├── 14-video-production-plan-video-13-contentstack-in-a-composable-dxp · text · 3 min ├── 15-video-production-plan-overview · text · 3 min ├── 16-video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call · text · 3 min ├── 17-video-production-plan-video-2-headless-foundations-and-designing-for-editors · text · 3 min ├── 18-video-production-plan-video-3-structured-content-and-api-contracts · text · 3 min ├── 19-video-production-plan-video-4-composition-query-performance-and-modeling-in-practice · text · 3 min ├── 20-video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice · text · 3 min ├── 21-video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk · text · 3 min ├── 22-video-production-plan-video-7-performance-images-environments-and-cli-migrations · text · 3 min ├── 23-video-production-plan-video-8-live-preview-architecture-and-preview-routing · text · 3 min ├── 24-video-production-plan-video-9-visual-builder-releases-and-future-state-preview · text · 3 min ├── 25-video-production-plan-video-10-workflow-automation-hub-and-branch-strategy · text · 3 min ├── 26-video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks · text · 3 min ├── 27-video-production-plan-video-12-maintainability-governance-and-long-term-ownership · text · 3 min ├── 28-video-production-plan-video-13-contentstack-in-a-composable-dxp · text · 3 min ``` ## Lessons ### Lesson 01 — Video Production Plan : Overview #### Lesson text # Video Production Plan This curriculum spans 8 courses, 17 modules, and 62 lessons. Recording one video per lesson would be unsustainable. Instead, this plan bundles lessons into 13 high-value videos that cover the full certification path. ## Strategy * Bundle related lessons into cohesive narratives * Prioritize topics that are hardest to learn from text alone (architecture, implementation, visual features) * Use the Veda jewelry scenario as the consistent thread throughout * Estimated total runtime: ~4-5 hours * If time is tight, the 6 critical videos alone cover the core certification path in ~2 hours ## Priority Tiers Priority Videos Est. Runtime Description Critical 6 ~2-2.5 hours Record first. Hardest to learn from text, highest visual value. Core 5 ~1.5-2 hours Completes full curriculum coverage. Polish 2 ~30-40 min Conceptual and forward-looking. Can ship as text-only if needed. Total 13 ~4-5 hours ## Suggested Recording Order Record impact-first, not sequentially. The critical videos cover the concepts that are hardest to learn from text and that developers get wrong most often. ### Phase 1: Critical 1. [Video 3 — Structured Content and API Contracts](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/03-structured-content-and-api-contracts) 2. [Video 5 — API Architecture, Authentication, and Query Surface Choice](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/05-api-architecture-authentication-query-surface) 3. [Video 6 — Fetching and Rendering Content with the SDK](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/06-fetching-and-rendering-content) 4. [Video 8 — Live Preview Architecture and Preview Routing](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/08-live-preview-architecture-and-routing) 5. [Video 9 — Visual Builder, Releases, and Future-State Preview](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/09-visual-builder-releases-future-state) 6. [Video 11 — When To Customize: Configuration vs Apps vs Webhooks](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/11-when-to-customize) ### Phase 2: Core 1. [Video 7 — Performance, Images, Environments, and CLI Migrations](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/07-performance-images-environments-cli) 2. [Video 10 — Workflow, Automation Hub, and Branch Strategy](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/10-workflow-automation-branch-strategy) 3. [Video 2 — Headless Foundations and Designing for Editors](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/02-headless-foundations-and-designing-for-editors) 4. [Video 4 — Composition, Query Performance, and Modeling in Practice](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/04-composition-query-performance-modeling) 5. [Video 1 — Start Here: Certification Roadmap and First API Call](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/01-start-here-certification-roadmap) ### Phase 3: Polish 1. [Video 12 — Maintainability, Governance, and Long-Term Ownership](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/12-maintainability-governance-ownership) 2. [Video 13 — Contentstack in a Composable DXP](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/13-contentstack-in-composable-dxp) ## Expansion Candidates If learner feedback shows specific modules need more depth, these are the best candidates for splitting into 2-part videos: * **Module 3.2 (Fetching and Rendering):** split into fetch/query basics + performance/images/frontend patterns * **Module 4.1 (Live Preview and Visual Builder):** split into preview architecture + Visual Builder implementation * **Module 6.1 (Extension Architecture):** split into decision framework/marketplace + custom apps/webhooks ## Recording Tips * **Videos 1-7 (Courses 0-3):** Heavy on screencasts — Contentstack UI, code editor, and terminal side by side * **Videos 8-9 (Course 4):** Most visually compelling — show Live Preview and Visual Builder in full editorial flow * **Video 10 (Course 5):** Mix of UI walkthroughs and architecture diagrams * **Videos 11-12 (Course 6):** Developer Hub demos + conceptual slides * **Video 13 (Course 7):** Architecture diagrams with occasional platform demos * **All videos:** Use the Veda jewelry scenario as the consistent thread * **All videos:** End each video with a clear transition to what comes next in the curriculum #### Key takeaways - Connect **Video Production Plan : Overview** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 02 — Video Production Plan : Video 1 — Start Here - Certification Roadmap and First API Call #### Lesson text # Video 1 — Start Here: Certification Roadmap and First API Call Attribute Details Course 0 (Orientation) Covers Lessons 0.1.1, 0.1.2, 0.1.3 Priority Core Length 10-15 min Format Screencast (Contentstack UI + terminal) Status Not started ## Why This Video Matters Gives learners an early win and reduces drop-off at the start of the certification. This is the first thing people see — it needs to be welcoming and confidence-building. ## Outline 1. Who this certification is for and what the learner is expected to already know 2. How the curriculum is structured across 7 courses 3. Quick tour of the documentation ecosystem: developer docs, API references, SDKs (JS, Python, Java, .NET, Ruby, Swift, Dart, Flutter) 4. Regional API base URLs, Postman collections, GitHub repos 5. Open the Contentstack dashboard: show a stack, a content type, and an entry 6. Make a live Content Delivery API call with curl — walk through the request and the JSON response 7. Repeat the same query with the JavaScript SDK to show the abstraction layer 8. How to study the rest of the curriculum efficiently ## Key Lines "This certification is easier if you think of it as one continuous build journey, not a set of disconnected lessons." "You do not need to memorize every API detail. You need to know where to find the right reference quickly." "You just fetched your first entry. Everything in this certification builds on this." ## Detailed Talking Points ### 1\. Who this certification is for and what the learner is expected to already know * "This certification is for developers who build on top of Contentstack — frontend devs consuming delivery APIs, fullstack devs wiring up preview and webhooks, backend devs integrating into platform architectures." * Explain that no prior Contentstack experience is needed, but they should be comfortable with HTML/CSS/JS, REST APIs, JSON, and have used fetch or axios before. * Mention the free developer plan — they can sign up and get a stack before starting. * Call out what this certification does NOT cover: pricing, sales/marketing features (Personalize, A/B testing), admin tasks (SSO/SAML), or framework-specific tutorials. "This is about Contentstack concepts that apply no matter what framework you use." ### 2\. How the curriculum is structured across 7 courses * Walk through each course in one sentence: * Course 1: Foundations — mental model for headless, the 5 building blocks * Course 2: Content Modeling — designing schemas that serve editors AND APIs * Course 3: APIs and Tooling — Delivery API, Management API, REST vs GraphQL, SDK, CLI * Course 4: Preview and Visual Builder — Live Preview, Visual Builder, releases * Course 5: Workflows and Branches — content lifecycle, automation, branching * Course 6: Extensions — when to customize, apps, webhooks * Course 7: Integrations — composable DXP, Launch, Automate, Personalize * Emphasize: "Course 1 is mandatory first. After that, you can jump to whatever is most relevant to your current work." * Mention the lesson structure: every lesson has a TL;DR, core content, practice activity, common mistakes, and self-check questions. "The self-checks test application, not recall. If you can't answer them, re-read before moving on." ### 3\. Quick tour of the documentation ecosystem * Show the developer docs landing page at [contentstack.com/docs/developers/](/docs/developers/) — "Bookmark this. You'll come back to it constantly." * Three API surfaces: Content Delivery API (REST), Content Management API (REST), GraphQL Content Delivery API. Briefly explain each in one sentence. * "The Delivery API is what your frontend calls in production. The Management API is for automation, migrations, and admin scripts. GraphQL lets you request exactly the fields you need." * Mention the SDKs: JavaScript/Node.js (most common), Python, Java, .NET, Ruby, Swift, Dart/Flutter. "You don't need to learn them all. Pick the one for your stack." * Point out the SDK docs vs raw API reference distinction: "When an SDK method behaves unexpectedly, check the raw API reference or the SDK source on GitHub. SDK docs sometimes lag behind." ### 4\. Regional API base URLs, Postman collections, GitHub repos * Show the region table: NA (cdn.contentstack.io), EU (eu-cdn.contentstack.com), Azure NA (azure-na-cdn.contentstack.com), Azure EU (azure-eu-cdn.contentstack.com), GCP NA (gcp-na-cdn.contentstack.com). * "Using the wrong base URL is the number one cause of 'stack not found' errors. It's not an auth problem — it's a region mismatch." * Show where to find your stack's region in the dashboard under stack settings. * Mention Postman collections — "Import the collection, set up an environment with your api\_key, access\_token, and base\_url, and you can explore every endpoint without writing code." * Point to [github.com/contentstack](https://github.com/contentstack) — SDKs, sample apps (Next.js, Gatsby, Nuxt, Angular), CLI tools. * Mention npm install -g @contentstack/cli — "We'll use this heavily in Course 3, but know it exists." ### 5\. Open the Contentstack dashboard: show a stack, a content type, and an entry * Open the Veda stack in the dashboard. Point out the stack API key in settings. * Navigate to Content Types. Open the product content type. "This is both a schema and an editor interface. Every field UID you see here becomes a JSON key in the API response." * Point out the field UIDs vs display names — short\_description is the API key, "Short Description" is what editors see. * Open a published entry (e.g., a Veda product). Show the title, locale, reference fields, and asset fields. * Note the environment and the delivery token scoped to it. ### 6\. Make a live Content Delivery API call with curl * Switch to terminal. Run: curl -s "https://cdn.contentstack.io/v3/content\_types/product/entries?environment=development" \\ -H "api\_key: YOUR\_KEY" \\ -H "access\_token: YOUR\_TOKEN" | jq * Walk through the response: the entries array, field UIDs matching the schema, system fields like uid, locale, timestamps. * "Look at one entry. Which fields would a listing page need? Which fields would a detail page need? Which fields stay internal to editors? This is the core shift — you're not building around pages the CMS owns. You're consuming structured JSON." * If it fails: "Check region first, then environment, then token scope. Most first-time failures aren't auth issues — they're context mismatches." ### 7\. Repeat the same query with the JavaScript SDK * Show the SDK initialization code: import Contentstack from "@contentstack/delivery-sdk"; const stack = Contentstack.stack({ apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!, deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN!, environment: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_ENVIRONMENT!, region: Contentstack.Region.US, }); const result = await stack.contentType("product").entry().query().find(); console.log(result.entries\[0\]); * "Same content, same response shape, but now through a developer-friendly library. You don't need to master this yet. The point is seeing that you have two ways in: raw HTTP and SDK." ### 8\. How to study the rest of the curriculum efficiently * "Work through Course 1 first. Every later course assumes you understand its vocabulary." * "Keep a stack open while you study. Reading about content types is useful; creating one and fetching from it through the API is where it sticks." * "Give the self-check questions real effort. If you can't answer them, the next lesson will be harder." * "This curriculum is also a reference. When you hit a real-world content modeling decision or API challenge, come back to the relevant lesson." ## Screen: What to Show 1. Curriculum site — show the course catalog / home page briefly 2. Developer docs — [contentstack.com/docs/developers/](/docs/developers/) landing page, scroll through the navigation 3. API reference — open the Content Delivery API reference, show an endpoint page briefly 4. Region table — either the docs page or a slide showing the 5 regions and their base URLs 5. Contentstack dashboard — navigate to: Settings → API keys (show stack API key and region), Content Types → open product, Entries → open a Veda product entry 6. Terminal — run the curl command, pipe to jq, show the JSON response 7. Code editor — show the SDK initialization code, run it, show console output 8. Postman (optional) — quickly show a pre-configured Postman collection request ## Veda Scenario Thread Introduce Veda here for the first time: "Veda is an upscale all-gender jewelry line — four distinct sets inspired by early 2000s pop culture, reinterpreted with modern luxury. Silver, gold, diamonds. This isn't just an example — it's the storefront you'll return to across every course. The same products, categories, and pages will anchor content modeling, API calls, preview, workflows, and integrations." Use a Veda product entry for the curl demo and SDK demo so learners connect to it immediately. ## Transitions * Curriculum overview → docs tour: "Before we start building, let me show you where to find answers when you need them." * Docs tour → regional URLs: "One thing that trips people up immediately — your API base URL depends on your region." * Regional URLs → dashboard walkthrough: "Let's look at the actual stack we'll be working with." * Dashboard → curl call: "Now let's prove this works. I'm going to fetch this entry through the API." * Curl → SDK: "Same query, but this time through the JavaScript SDK." * SDK → study tips: "You just fetched your first entry. Here's how to make the rest of this certification as efficient as possible." * Closing → Video 2: "Next, we'll zoom out and build the mental model for headless architecture — what Contentstack is responsible for, what you're responsible for, and why that distinction matters for every decision you'll make." ## Common Mistakes to Call Out 1. Treating the dashboard as the whole product — "If you only click around the UI and never inspect the API response, Contentstack still feels like a form builder. It's not. It's a structured content platform. The API response is the product." 2. Using the wrong region or environment — "Many first-time delivery failures aren't authentication failures. They're context mismatches: wrong base URL, wrong environment name, or content that was never published to that environment." 3. Waiting until Course 3 to touch the APIs — "Don't do this. One successful request now pays off for the rest of the path. The certification gets easier when you connect concepts to a real response early." ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 1 — Start Here - Certification Roadmap and First API Call** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 03 — Video Production Plan : Video 2 — Headless Foundations and Designing for Editors #### Lesson text # Video 2 — Headless Foundations and Designing for Editors Attribute Details Course 1 (Foundations) Covers Lessons 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.2.1, 1.2.2, 1.2.3 Priority Core Length 15-20 min Format Slides/diagrams + Contentstack UI walkthrough + good vs bad content type comparison Status Not started ## Why This Video Matters Establishes the mental model that everything else depends on. If learners don't understand headless boundaries and the editor-developer relationship, every later topic is harder. ## Outline 1. What headless really means: the CMS does not own rendering — developers own framework, hosting, and rendering strategy 2. Compare monolithic (WordPress/Drupal renders pages) vs headless (API-first, frontend renders) 3. Gains: framework freedom, deployment flexibility, multi-channel delivery, independent scaling, reduced security surface 4. Losses: no built-in page rendering, no URL routing, preview requires implementation, content-to-page mapping is your job 5. The 5 building blocks: Stacks, Content Types, Entries, Assets, Environments — walk through each in the UI 6. Draw the boundary: what Contentstack IS vs IS NOT 7. Content types as dual-purpose: API contract AND editor interface 8. Field UIDs become API keys; Display Names become editor labels — show this mapping live 9. Constraints vs flexibility: over-constraining causes workarounds; under-constraining pushes quality control to frontend 10. Collaboration patterns that work vs anti-patterns ## Key Lines "Headless is not just a tooling choice. It is a responsibility shift." "A content type is not only a schema. It is also an editor interface." "Your content model is a product. Your editors are your users." ## Detailed Talking Points ### 1\. What headless really means * Start with the misconception: "headless" is the most misused word in CMS marketing. Vendors slap it on everything. What it actually means is one architectural fact: the CMS does not own the rendering layer. * The metaphor: the "head" in a traditional CMS is the presentation layer — templates, routing, HTML output. Remove that, and you have a headless CMS. * Ownership, not tooling: headless is not a framework decision. You could build a headless frontend with jQuery and server-rendered PHP. The CMS is headless because it does not render — your framework choice is a separate decision. * In Contentstack specifically: you define content types, create entries, and the platform serves them via REST and GraphQL APIs. It does not generate a single HTML page. No template engine, no routing layer, no SSR pipeline inside the platform. * The Veda angle: when an editor publishes the "Matrix Link Bracelet" product entry, Contentstack makes that JSON available via API. Whether it becomes a web page, a mobile screen, or a kiosk display depends entirely on what you build. * The responsibility shift: everything downstream of the API — framework, hosting, rendering strategy, URL structure, page composition — is yours to build and maintain. ### 2\. Monolithic vs headless comparison * WordPress example: create a page, hit Publish, and the CMS writes to MySQL, selects a PHP template from your active theme, executes it, and returns rendered HTML. The CMS owns every step from storage to browser output. * Drupal follows the same pattern: Twig templates, render arrays, theme layer — CMS controls the full response lifecycle. * Contentstack: editor publishes an entry, content lands on the delivery API. Full stop. Your Next.js app, your Nuxt site, your Astro project makes an API call, gets JSON, renders it however you decided. * Key point: this is an architectural distinction, not a quality judgment. Calling something headless does not make it better. It means the rendering responsibility moved. * Tie it together: the separation means CMS and frontend have independent deployment lifecycles, separate hosting, separate tech stacks. Content publishing and code deployment are decoupled. ### 3\. What you gain * Framework freedom: React, Vue, Svelte, Astro, Qwik — all valid because the CMS only provides content via API. You can also switch frameworks without migrating the CMS — build a new frontend, point it at the same APIs, retire the old one. * Deployment flexibility: your frontend is an independent app. Deploy it to Vercel, Netlify, Cloudflare Pages, AWS, your own infrastructure. Optimize for your traffic patterns and cost constraints. * Multi-channel delivery: one Contentstack stack can serve a website, mobile app, digital kiosk, voice assistant. For Veda, the same product content could power the web storefront and an in-store display. * Independent scaling: a viral product launch puts load on your frontend and the CDN-backed delivery API, not on the content management system. Editors keep working uninterrupted. * Security surface reduction: end users never touch the CMS directly. No WordPress-style vulnerabilities where the same app that serves pages also processes admin requests. * Separation of concerns: content team works in the CMS, dev team works on the frontend. The API contract (content model) is the boundary between them. ### 4\. What you give up * No built-in page rendering: creating a content type and entries gives you structured data behind an API. To see a web page, you build a frontend. This includes layout, component mapping, responsive design, accessibility, performance optimization. * No URL routing: WordPress auto-generates /blog/my-post-title/. In headless, you design the URL structure, implement routing in your framework, and handle redirects, canonical URLs, sitemap generation yourself. This is commonly underestimated. * Preview requires implementation: in WordPress, "Preview" just works because the CMS renders the page. In headless, you build preview mode — configure preview tokens, set up preview-aware routing, integrate the Live Preview SDK. Preview is a feature you build, not a feature you get. * Content-to-page mapping is your problem: a homepage might pull from Hero Banner, Featured Products, Latest Articles, and Promotional Banner content types. The composition logic, query strategy, and rendering orchestration are all yours. * Editor experience depends on your investment: if you do not implement Live Preview, editors cannot see changes in context. If you skip Visual Builder, editors cannot edit on-page. Two identical Contentstack projects can have radically different editor experiences based purely on developer effort. ### 5\. The 5 building blocks * **Stacks:** the top-level container. Everything lives inside a stack — content types, entries, assets, environments, locales, branches, tokens, workflows, webhooks. Think of it as a project boundary. For Veda, one stack named veda-revival-web holds everything for the storefront. * **Content Types:** schemas that define the structure of content. Declare fields, data types, validation rules. A content type defines the shape of the JSON the API returns. For Veda: Product (title, short\_description, price, media, product\_line reference), Product Line, Category, Page with Modular Blocks. * **Entries:** instances of content types. The data. When an editor clicks "Create Entry" and selects a content type, they get a form generated from the schema. Entries exist independently of any page — a Product entry is structured data until your frontend fetches and renders it. * **Assets:** files in Contentstack's repository — images, PDFs, videos. Each gets a CDN-backed URL. Image transformation pipeline built in: append ?width=400&format=webp to resize and convert on the fly. No separate image processing service needed. * **Environments:** deployment targets. development, staging, production. Each has its own delivery token. Publish an entry to staging for review without it appearing on production. This is how you prevent draft content from leaking to the live site. * The fundamental loop: model content types, create entries, publish to environments, deliver via API. Every other feature extends this loop. ### 6\. Drawing the CMS boundary * The boundary principle: Contentstack is the system of record for content. Content means structured editorial material — what editors create, review, approve, and publish through editorial workflows. * What it IS: content storage with versioning, editorial workflows, multi-environment publishing, API delivery (REST + GraphQL + CMA), asset hosting with CDN and image transforms, webhooks for event-driven architecture, Live Preview and Visual Builder infrastructure, content branches for safe schema evolution. * What it IS NOT: a web host, a server-side application runtime, an end-user authentication system, an e-commerce transaction processor, a general-purpose database, a job scheduler, a URL router. * Concrete examples to drive the point home: Contentstack can store product descriptions for Veda, but it does not process orders — that is Shopify or commercetools. It can store a URL slug in a field, but it does not enforce that as a route — your frontend does that. It manages CMS user access, but it has no concept of your website's visitors. * Why this matters: clear boundaries keep the CMS performant and make team responsibilities unambiguous. A system that tries to do everything does nothing well. ### 7\. Content types as dual-purpose * This is the single most important concept for developers working in a headless CMS: a content type is simultaneously an API contract AND an editor interface. * When you open the Content Type Builder and add fields, every field you drag onto the canvas appears as an input element in the entry editor. You are writing a schema and designing a UI at the same time. * The field's Display Name becomes the label editors read. The field's help text becomes the guidance they rely on. The field's position determines the order editors work through. * For Veda: a Product content type is both the JSON shape your Next.js app consumes and the form an editor fills out 50 times a day. * Consequence: if you name fields for the API and ignore the editor, you get a technically clean schema with a terrible editing experience. If you design only for editors without thinking about the API, you get messy JSON that is painful to consume. ### 8\. Field UIDs become API keys * Every field has two names: the UID (machine-readable, used in API responses — becomes a JSON key) and the Display Name (human-readable, shown to editors). * Developers focus on UIDs because that is what appears in code. Editors never see UIDs — they only see Display Names. * Show this mapping live: a field with UID short\_description and Display Name "Marketing Tagline (max 120 chars)" — the editor sees the friendly label, the API returns the clean key. * Good Display Names communicate purpose, not just data type. Not "Image" but "Hero Image (1920x1080)." Not "URL" but "External Link (full URL including https)." Not "Body" but "Product Description (long-form content)." * Help text is inline documentation editors actually read. It answers: What goes here? Why does it matter? What are the constraints? Example: "Write a 150-160 character summary of this page. This appears in Google search results below the page title." * Field order matters: editors work top to bottom. Put identity fields first (title, slug), then primary content, then supporting content (images, references), then metadata (SEO) last. ### 9\. Constraints vs flexibility * Over-constraining forces workarounds: if every field is mandatory, editors upload placeholder images, enter dummy text, misuse fields. The data becomes unreliable not because editors are careless but because the system gave them no legitimate path. * Veda scenario: a Product content type with a mandatory "Featured Image" field. The team wants to publish a placeholder product without an image yet. They upload a blank white square. The frontend now displays a meaningless image. * Under-constraining pushes quality control to the frontend: no mandatory fields means inconsistent content. One author adds SEO descriptions, another skips them. One uploads 1920x1080 hero images, another uploads phone screenshots. The developer writes defensive code for every variation — expensive to build, hard to maintain. * The guideline: make a field mandatory only if the frontend breaks without it. Use help text as a behavioral guardrail for everything else. * Modular Blocks as the sweet spot: define a set of named blocks (Hero, Rich Text, Image Gallery, CTA, Video Embed), each with their own fields. Editors compose pages by selecting and ordering blocks. They get creative freedom within developer-defined structure. The API response is a typed array — no surprises. * Start loose, tighten based on data: at launch, keep constraints minimal. After three months, you have real usage data. See which fields are always filled (candidates for mandatory), which follow patterns (candidates for validation), which are never used (candidates for removal). ### 10\. Collaboration patterns vs anti-patterns * **Pattern: Content model co-design** — 30-minute session per content type with one or two editors. Open the Content Type Builder, walk through each field together. Developers learn editors call "Summary" "Teaser Text." Editors learn the Hero Image needs 16:9 aspect ratio. Both discover the Author reference needs to allow multiple authors. * **Pattern: Staged rollout** — do not deploy a new content type directly to production. Use dev environment first, invite editors to create test entries with real content (not lorem ipsum), gather feedback, iterate, then deploy to production. Adds a few days but prevents weeks of rework. * **Pattern: Documentation as conversation** — put documentation in the content type itself. Help text on every field, content type description explaining when to use it. External wikis decay. In-context help travels with the content type. * **Pattern: Preview-driven development** — implement Live Preview early, not as post-launch polish. When editors see their changes rendered in real time, they need less guidance about constraints. An editor who uploads a low-res image and sees it blurry in preview understands the requirement viscerally. * **Anti-pattern: "Dev builds, editor adapts"** — developer designs content types in isolation, editor sees them for the first time when entering content. Result: field names do not match editor vocabulary, order is wrong, help text is missing, constraints are either too tight or nonexistent. Two hours to design, two weeks to stabilize. * **Anti-pattern: "Editor-designed content types"** — editors specify exactly what fields they want, developers implement without pushback. Editors think in pages and layouts — they request "Left Column Text" and "Right Column Text" which encodes layout into the content model. When design changes, field names become misleading. * **Anti-pattern: "Change on request"** — every editor request becomes a field addition. Over months, content types accumulate 35 fields, most empty in 90% of entries. This is field sprawl — the content modeling equivalent of tech debt. ## Screen: What to Show ### 1\. What headless really means * Open a simple diagram (prepared slide) showing: CMS box on the left labeled "Content Storage + API," arrow pointing right to multiple frontend boxes (web, mobile, kiosk). Contrast with a monolithic diagram where everything is one box. ### 2\. Monolithic vs headless comparison * Side-by-side slide: left side shows WordPress flow (Content -> PHP Template -> HTML -> Browser, all inside one box). Right side shows Contentstack flow (Content -> API -> \[gap\] -> Your Frontend -> Browser, with the gap highlighted as "your responsibility"). ### 3\. What you gain * Quick slide listing the six gains with icons. No need to linger — this is a verbal section. ### 4\. What you give up * Same format: slide listing the five losses. Highlight "Preview requires implementation" with a callout box — this surprises people the most. ### 5\. The 5 building blocks * Switch to the Contentstack UI. Open the Veda stack. * Show the stack dashboard — point out the left-hand navigation sections. * Click into Content Models and open the Product content type. Show the field list in the Content Type Builder. * Click into Entries and show the list of Product entries. Open the "Matrix Link Bracelet" entry to show the editor form generated from the content type. * Click into Assets and show the folder structure with Veda product photography. * Click into Settings > Environments and show the three environments (development, staging, production) with their base URLs. * Briefly show the relationship: "Content type defines the schema, entry is an instance, assets are referenced, published to an environment, delivered via API." ### 6\. Drawing the CMS boundary * Return to the slide deck. Show a two-column slide: "Contentstack Does" on the left (content storage, workflows, API delivery, asset CDN, webhooks, Live Preview infra, branches) and "Your Responsibility" on the right (hosting, rendering, routing, auth, e-commerce, scheduled jobs, URL management). Draw a clear vertical line between them. ### 7\. Content types as dual-purpose * Back in the Contentstack UI. Open the Product content type in the Content Type Builder. Point at the field list and say: "This is simultaneously the API contract and the editor interface." * Then open an entry of that content type side by side (or switch between tabs) to show how each field in the builder maps to an input element in the entry editor. ### 8\. Field UIDs become API keys * In the Content Type Builder, click on a field (e.g., the short\_description field on the Product content type). Show the UID field and the Display Name field side by side in the field settings panel. * Then open a browser tab with the Contentstack API Explorer or a raw JSON API response for a Product entry. Point at the JSON key that matches the UID. Show that the Display Name does not appear in the API — it is only for editors. * Scroll through the entry editor and point out help text on fields, showing how it appears directly below the label. ### 9\. Constraints vs flexibility * In the Content Type Builder, open the Product content type. Click on a field and show the "Mandatory" toggle and validation rules (min/max length, regex). * Create or show a comparison: a content type with every field marked mandatory vs one with sensible defaults. If possible, show a screenshot of the editor hitting a wall of red validation errors vs a clean save experience. * Open a Page content type that uses Modular Blocks. Show the block type definitions (Hero Block, Rich Text Block, CTA Block). Switch to an entry and show how editors add and reorder blocks — the compositional freedom within guardrails. ### 10\. Collaboration patterns vs anti-patterns * Show a slide with two columns: "Patterns That Work" (co-design, staged rollout, in-context docs, preview-driven dev) and "Anti-Patterns" (dev builds alone, editor-designed types, change on request). * Quick screenshare: open a content type and show the Description field (where you document when to use this content type). Show a field's help text as an example of documentation that lives in-context. * If Live Preview is configured on the Veda stack, show the Live Preview panel — editor changes a product title, preview updates in real time. This is the money shot for this section. ## Veda Scenario Thread * **Opening (building blocks):** introduce the Veda stack as the running example. "We are building the storefront for Veda: The Revival Collection — a luxury jewelry brand. Everything we talk about today, we will see in this stack." * **Stacks:** the Veda stack (veda-revival-web) is the project container. All product content, collection pages, and campaign assets live here. If Veda launches a mobile app later, it can consume from the same stack — multi-channel from a single content source. * **Content Types:** walk through Veda's Product content type (title, short\_description, price, media, product\_line reference, category reference), Product Line content type (Digital Dawn collection), and Page content type with Modular Blocks for the homepage. * **Entries:** show real Veda entries — "Matrix Link Bracelet" at $295 in the Digital Dawn product line. Show a Page entry for "The Revival Collection" homepage composed from modular blocks. * **Assets:** Veda product photography, collection hero images, brand logo — all managed in the asset repository with CDN delivery and image transforms. * **Environments:** Veda's three environments — development (where devs test rendering), staging (where editors preview before go-live), production (the live storefront). * **CMS boundary:** Veda sells jewelry, but Contentstack does not process orders. Product content lives in the CMS; transaction processing lives in the commerce platform. The URL /products/matrix-link-bracelet is defined by the frontend, not the CMS. * **Dual-purpose content type:** the Product content type is both the JSON shape the Veda Next.js app consumes and the form editors fill out when adding new jewelry pieces to the catalog. * **Constraints:** the Product title and price are mandatory (the frontend breaks without them). The promotional tagline is optional with help text. The featured image is strongly recommended via help text but not mandatory — because sometimes a product is listed before photography is ready. * **Collaboration:** when the Veda team designed the Product content type, they sat with the merchandising editor and walked through each field. The editor pointed out that "short\_description" should be labeled "Marketing Tagline (max 120 chars)" because that matches their content brief. That 30-minute session prevented weeks of confusion. ## Transitions 1. From intro to headless definition: "Before we touch any code or UI, we need to get one foundational concept right — what headless actually means, in terms of responsibility, not buzzwords." 2. **From headless definition to monolithic comparison:** "To make this concrete, let's compare what happens when you hit Publish in WordPress versus what happens in Contentstack." 3. **From comparison to gains:** "That separation sounds like you are losing features — and you are — but you are gaining something significant in return." 4. **From gains to losses:** "Now let's be honest about the other side of that trade, because pretending headless is universally better does not help anyone build real projects." 5. **From losses to building blocks:** "Alright, you understand the architecture and the tradeoffs. Let's get hands-on and look at the five building blocks you will work with every day." 6. **From building blocks to CMS boundary:** "Now that you have seen the pieces, let's draw a clear line around what Contentstack is responsible for and what is yours." 7. **From boundary to dual-purpose content types:** "This boundary leads directly to a concept that changes how you think about content modeling: your content type is not just a schema." 8. **From dual-purpose to field UIDs:** "Let's zoom in on the mechanics — how field UIDs map to API keys and Display Names map to editor labels." 9. **From field UIDs to constraints vs flexibility:** "Now that you see how fields shape both the API and the editor experience, the question becomes: how tightly do you control what editors can do?" 10. **From constraints to collaboration patterns:** "Getting the constraints right is not something you do alone — it requires working with the people who actually use the system every day." 11. **Closing transition to Video 3:** "You now have the mental model: headless architecture, the five building blocks, content types as dual-purpose contracts, and how to work with editors. In the next video, we go deep on the content modeling itself — field types, references, Modular Blocks, and the design patterns that separate a clean content model from a messy one." ## Common Mistakes to Call Out 1. **Equating "headless" with "better":** headless describes architecture, not quality. A poorly implemented headless site is worse than a well-maintained WordPress site. The architecture enables flexibility; it does not guarantee outcomes. 2. **Assuming the CMS handles routing or page generation:** developers from WordPress/Drupal expect the CMS to produce pages or manage URLs. In headless, the CMS produces structured content via APIs. Routing, URL generation, page composition, and HTML rendering are entirely the frontend's job. 3. **Treating headless as a framework decision:** choosing React or Next.js is not what makes a CMS headless. The CMS is headless because it does not own rendering. The framework is your choice; the architecture is the CMS's characteristic. 4. **Adopting headless without frontend development capacity:** the most expensive version of this mistake is an organization that chooses a headless CMS, then discovers every page change requires developer involvement because no one anticipated the frontend build cost. 5. **Underestimating preview and editorial tooling investment:** developers focus on the API and rendering pipeline. Editors need to see content in context. Treating Live Preview and Visual Builder as optional polish leads to editor frustration and slower content operations. 6. **Comparing CMS license cost instead of total cost of ownership:** frontend development, hosting infrastructure, preview tooling, deployment pipelines, and ongoing maintenance are all costs that exist in headless but are partially absorbed in traditional CMS setups. 7. **Confusing content types with pages:** a content type called "Page" defines fields, not a rendered page. Multiple entries from different content types compose a single page, and a single entry might appear on multiple pages. 8. **Using one environment for everything:** running dev, staging, and production through a single environment removes the ability to preview and validate content before it reaches end users — and risks leaking draft content to the live site. 9. **Storing non-content data in content types:** feature flags, app config, transactional records — these clutter the editorial interface and push the CMS beyond its design. Use environment variables or dedicated configuration services. 10. **Naming fields for the API instead of the editor:** using terse names like "desc" or "img\_alt" as Display Names forces editors to decode developer shorthand. Always write Display Names in plain language that describes what the editor should enter. 11. **Skipping help text entirely:** developers assume editors understand the content model. They do not. Every field without help text is a field where editors must guess or ask. 12. **Making every field mandatory on the first iteration:** developers who have not seen real content overestimate what is required. Start with only structurally essential fields as mandatory and tighten after observing real editorial usage. 13. **Treating content type design as a one-time task:** content types designed before editors start working almost always need revision. Plan for iteration and build a feedback loop into your project. 14. Relying on external documentation instead of in-context help text: a Confluence page with content type docs is better than nothing, but it decays within months. Put essential guidance inside the content type itself. 15. Skipping preview integration because it is "not a priority": Live Preview is the single most effective tool for reducing editor errors and support requests. Implementing it early saves more time than almost any other developer investment. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 2 — Headless Foundations and Designing for Editors** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 04 — Video Production Plan : Video 3 — Structured Content and API Contracts #### Lesson text # Video 3 — Structured Content and API Contracts Attribute Details Course 2 (Content Modeling), Module 2.1 Covers Lessons 2.1.1, 2.1.2, 2.1.3, 2.1.4 Priority Critical Length 18-25 min Format Screencast (Contentstack UI + code editor side-by-side) Status Not started ## Why This Video Matters This is one of the most important videos in the entire series. It shapes how learners think about content from the start. If the model is wrong, the frontend, editorial workflow, and APIs all become harder. ## Outline 1. The mindset shift: stop thinking in pages, start thinking in domain concepts 2. Three questions for every content type: Does the concept exist independently? Will it appear in multiple contexts? Would editors update it separately? 3. Veda example: Product, Product Line, Category, Page — four types connected by references instead of one giant page template 4. Content types as API contracts: every field UID becomes a JSON key in the response 5. Show a content type definition and the resulting API response side-by-side 6. Breaking changes: renaming or removing a field UID on published entries breaks frontends immediately. Adding fields is safe (null default) 7. TypeScript interfaces should mirror content type schemas 8. Global Fields: define a field group once, reuse across content types, changes propagate everywhere 9. When to use Global Fields (SEO metadata, addresses, CTAs used by 3+ types) vs when not to 10. JSON Rich Text Editor: structured document tree, not HTML string — show the raw JSON 11. Embedded entries/assets as reference nodes; rendering with @contentstack/utils 12. Custom RTE plugins: extending the editor toolbar via Developer Hub ## Key Lines "If the model is wrong, the frontend, editorial workflow, and APIs all become harder." "A content model is an agreement between the CMS and downstream consumers." "The question is not 'can we model this', but 'can we model this in a way that stays healthy over time'." ## Detailed Talking Points ### 1\. The mindset shift: stop thinking in pages, start thinking in domain concepts * Traditional CMS platforms organize content around pages — one URL, one template, one database row with everything bolted on. * That works until someone asks you to show the same product on a mobile app, a marketplace feed, or a store display. The page abstraction falls apart. * Structured content separates what the content is from where and how it appears. * Instead of a "Product Page" you model the domain concept "Product" — title, price, description, media. No layout, no template assumptions. * Authors think in entries, designers think in components, developers think in API consumers. Everyone stops coupling to a single page template. * The CMS becomes a content API, not a page factory. ### 2\. Three questions for every content type * Before you create a content type, run it through three questions. * First: does this concept exist independently? A product line like Digital Dawn exists whether or not it has products yet. That means it deserves its own content type, not a text field inside Product. * Second: will this content appear in more than one context? If categories show up on product pages, category landing pages, and navigation menus, they need to be their own type with references — not embedded text you copy-paste. * Third: would editors need to update this independently? If changing a product line description should not require opening every product, the product line must be a separate entry. * These three questions consistently push you toward smaller, focused content types connected by references. * If the answer is "no" to all three, it can stay as a field group or a group field inside the parent type. ### 3\. Veda example: Product, Product Line, Category, Page * Walk through the Veda jewelry catalog as a concrete migration from page-oriented to structured content. * In a page CMS, a single product page row holds title, description, price, images, product line name, category name, SEO metadata — everything in one record. * In Contentstack, decompose into four content types: Product (title, url, short\_description, description, price, media, product\_line reference, category reference), Product Line (title, url, description, image, products reference), Category (title, url, description, media), Page (title, url, components as modular blocks). * Product references Product Line and Category — the product line description exists in exactly one place. Change it once, every product reflects the update. * The mobile app fetches Product with include\[\]=product\_line and gets clean JSON. The marketplace feed requests only title, price, and media using field projection. No HTML parsing, no screen-scraping. * Show the multi-channel reuse table: Website gets full product with description and images. Mobile app gets product summary, price, media. Marketplace feed gets title, price, short description, first image. Email campaign gets title, short description, hero image, link. Partner API feed gets product data without branding. In-store display gets product images and QR code. * One content model, six channels, zero duplication. ### 4\. Content types as API contracts: every field UID becomes a JSON key * This is the big mental model shift for developers: a content type is not just a form for editors. It is simultaneously a JSON schema that your frontend codes against. * The moment you save a content type with a field UID of short\_description, that string becomes a key in every API response. Every frontend component reading entry.short\_description depends on it. * Field labels like "Short Description" are what editors see — those can change freely. Field UIDs like short\_description are the contract — those are locked in once you have published entries. * Use snake\_case consistently, be descriptive but concise, avoid abbreviations only your team understands. ### 5\. Show a content type definition and the resulting API response side-by-side * Open the Product content type in the Contentstack UI and point out the field labels and UIDs. * Switch to the API response JSON for a real Product entry — show how every field UID maps one-to-one to a JSON key. * Highlight that reference fields appear as stubs by default (just UIDs), and you add include\[\]=product\_line to resolve them. * Highlight that file fields return objects with url, filename, and MIME type. * Highlight the system fields that appear automatically: uid, locale, created\_at, updated\_at. ### 6\. Breaking changes vs. safe changes * Adding a new field to a content type is safe. Existing entries return null for the new field. Frontend code should handle null gracefully with optional chaining. * Removing a field is a breaking change. If the frontend reads product.media\[0\].url and you delete the media field, the component throws a runtime error. Remove the frontend dependency first, deploy, then delete the field. * Renaming a field UID breaks the contract immediately. The old key vanishes from API responses and the new key appears. Every line of frontend code referencing the old key fails. * Changing a field type is risky — converting a Number to Single Line Text changes the API output from 295 to "295". Code calling .toFixed(2) crashes. * Reordering fields in the schema has zero API impact — it only changes the editorial UI order. * The takeaway: treat field UIDs as public API surface, not internal details. ### 7\. TypeScript interfaces should mirror content type schemas * Show a TypeScript interface for the Product content type that matches the field UIDs exactly. * This gives you compile-time safety — if someone renames short\_description to summary, TypeScript catches the breakage before deployment. * Some teams generate TypeScript types directly from the content type schema using the CMA or the Contentstack CLI cs:content-type:get command. * The interface is your developer-side contract; the content type schema is your CMS-side contract. They should stay in sync. ### 8\. Global Fields: define once, reuse across content types, changes propagate * Global Fields solve the problem of maintaining identical field groups across multiple content types. * You create a Global Field under Settings > Global Fields — for example, an SEO Metadata global field with meta\_title, meta\_description, og\_image, and canonical\_url. * Then you add it to any content type. It appears in the editor as an expandable group, just like a regular Group field. * The difference: a Group field is defined inline inside one content type. A Global Field is defined centrally and referenced — changes propagate to every content type that uses it. * Think of it like a shared component in a design system. Define a Button once, use it on every page. * The API output is identical to a Group field — a nested JSON object. Frontend developers do not need to know whether it came from a Group or Global Field. ### 9\. When to use Global Fields vs. when not to * Use Global Fields when the same group of fields appears in three or more content types with identical structure: SEO metadata, address blocks, CTAs, social media links. * Do not use Global Fields for data that needs to be independently queryable — that should be a separate content type with references. A Category needs to be listed, filtered, searched — it cannot be a Global Field. * Do not use Global Fields when different content types need different variations of the field group. If Products need extra Schema.org fields that Pages do not, create two global fields or use a Group for the extension. * Do not use Global Fields for a group used by only one content type. A regular Group field avoids the management overhead. * Key distinction: References share content (one Product Line entry used by many products). Global Fields share structure (one field definition used by many content types). ### 10\. JSON Rich Text Editor: structured document tree, not HTML string * The JSON RTE is where structured content meets rich text — and it matters because HTML strings are opaque blobs you cannot traverse or transform. * An HTML RTE stores

Check out our Premium Widget

as a flat string. You cannot extract the product reference, validate the link, or repurpose the content for a mobile app. * The JSON RTE stores the same content as a tree of typed nodes — a root doc node, paragraph nodes, text leaf nodes with formatting flags like bold and italic. * Show the raw JSON structure: { "type": "doc", "children": \[{ "type": "p", "children": \[{ "text": "..." }\] }\] }. * Every node has a type, a UID, optional attrs, and children. Text nodes are leaf nodes with a text property and boolean formatting properties. * This tree is fully traversable. A mobile app can extract just the text. A voice assistant skips images. A web app renders every node with custom components. ### 11\. Embedded entries and assets as reference nodes; rendering with @contentstack/utils * Editors can embed entries from other content types directly within JSON RTE content — inline or as blocks. * The JSON RTE stores these as reference nodes with entry-uid and content-type-uid attributes. The data is not duplicated; it is referenced. * To get the full embedded entry data in the API response, you must add include\_embedded\_items\[\]= to your API call. Without it, you get bare UIDs and embedded entries silently disappear from rendered output. * On the frontend, install @contentstack/utils and use jsonToHtml to convert the JSON tree to HTML. Pass paths to specify which fields contain JSON RTE data. * For custom rendering, use the renderOption parameter with renderNode handlers for each node type — including a reference handler for embedded entries and assets. * In React, you can build a component-based renderer where each node type maps to a React component, giving you full control over rendering. ### 12\. Custom RTE plugins: extending the editor toolbar via Developer Hub * Custom plugins add toolbar buttons, custom element types, paste behaviors, and keyboard shortcuts to the JSON RTE editor. * Plugins are built with @contentstack/app-sdk and deployed through Developer Hub as Contentstack apps with an RTE Plugin location. * A plugin inserts custom node types into the JSON tree — for example, a "Callout" button that creates a node of type callout with a style attribute. * The custom nodes appear in the API response as regular nodes with your custom type values. Your frontend renderer must handle them — if it does not, they render as blank space. * This is a three-way coordination: the plugin developer defines the node type, the content modeler enables the plugin on specific JSON RTE fields, and the frontend developer implements the renderer. Document the custom node schemas the same way you document content type schemas. ## Screen: What to Show Outline item Screen instructions 1\. Mindset shift Show a wireframe of a traditional product page with everything in one record. Then switch to the Contentstack Content Models list showing Product, Product Line, Category, Page as separate types. 2\. Three questions Display the three questions as a text overlay or slide. Point at each one while explaining. 3\. Veda example Open the Product content type in Content Models. Scroll through the field list: title, url, short\_description, description, price, media, product\_line (reference), category (reference). Then open Product Line and Category to show their schemas. Show the multi-channel reuse table as a slide or overlay. 4\. API contracts Split screen: left side shows the Content Type Builder with field labels and UIDs visible. Right side shows a code editor with the equivalent JSON API response. Draw attention to how the UID column maps to JSON keys. 5\. Side-by-side definition and response Open the CMA endpoint GET /v3/content\_types/product in a REST client (Postman or terminal with curl + jq). Show the schema array. Then fetch a Product entry from the CDA at GET /v3/content\_types/product/entries/{uid} and place both responses side by side. 6\. Breaking changes In the Content Type Builder, hover over a field UID and demonstrate what happens conceptually if you rename it. Show a terminal or browser console with a "Cannot read property of undefined" error to illustrate the frontend breakage. Show the safe path: adding a new field and showing it returns null on existing entries. 7\. TypeScript interfaces Switch to VS Code. Show a TypeScript interface for Product that mirrors the content type UIDs. Show the compiler catching a wrong property name with a red underline. 8\. Global Fields Navigate to Settings > Global Fields. Create or open the SEO Metadata global field showing meta\_title, meta\_description, og\_image, canonical\_url. Then open a content type (e.g., Page) and show the SEO Metadata global field embedded as an expandable group. Show the API response with the nested seo object. 9\. Global Fields decision Show a simple decision table as a slide: "3+ content types with identical shape = Global Field. Independently queryable = Reference. One content type only = Group field." 10\. JSON RTE Create or open a JSON RTE field in the entry editor. Type a paragraph with bold text. Then switch to the API response and show the raw JSON document tree — the doc node, p node, text nodes with bold: true. Contrast with an HTML RTE field that returns a flat HTML string. 11\. Embedded entries and rendering In the JSON RTE editor, click the Embed Entry toolbar button and insert an entry. Show the API response with the reference node containing entry-uid and content-type-uid. Switch to VS Code and show the @contentstack/utils import and jsonToHtml call with a renderOption that handles the reference node type. 12\. Custom RTE plugins Show the Developer Hub > New App screen. Show a plugin code snippet in VS Code that registers a custom toolbar button. In the entry editor, click the custom button and show the custom node appearing. Then show the API response containing the custom node type. ## Veda Scenario Thread * Open with the problem: Veda currently has a monolithic "Product Page" template in their old CMS. Every product bundles title, description, price, images, product line text, category text, and SEO fields into one record. The marketing team wants to launch a mobile app, a marketplace feed for partners, and an email campaign — all pulling from the same product data. * In section 1-2, explain why the page model fails for Veda: the marketplace feed needs title, price, and one image without any HTML. The mobile app needs a product summary without layout artifacts. The email needs a hero image and a link. You cannot serve six channels from one page template. * In section 3, walk through the Veda decomposition: Product with its eight fields, Product Line (Digital Dawn, Urban Armor, Heritage Craft), Category (Earrings, Necklaces, Bracelets, Rings), and Page with modular blocks. Show how the Matrix Link Bracelet references Digital Dawn and Bracelets. * In section 4-6, use the Product content type as the live example of the API contract. Show the Matrix Link Bracelet's API response. Demonstrate that renaming short\_description to summary would break the ProductCard component. Show that adding a sale\_price field is safe — existing entries return null. * In section 7, show the TypeScript interface for Veda's Product type mirroring the content type schema. * In section 8-9, add the SEO Metadata global field to both the Product and Page content types for Veda. Show how one update to the global field (adding a robots\_directive field) propagates to both types. * In section 10-11, open the Veda Product's description field as a JSON RTE. Show an editor embedding a "Product Comparison" entry within the product description. Show the raw JSON with the reference node. Render it with @contentstack/utils. * In section 12, mention that Veda could build a custom "Care Instructions" callout plugin for the JSON RTE, allowing editors to insert standardized care instruction blocks within product descriptions. ## Transitions 1 to 2: "So if we are not thinking in pages, how do we decide what gets its own content type? Three questions." 2 to 3: "Let us apply those three questions to the Veda jewelry catalog and see what content types fall out." 3 to 4: "Now that we have our four content types, here is the part most people miss — every field UID you just defined is a public API contract." 4 to 5: "Let me prove that to you by putting the content type definition next to the actual API response." 5 to 6: "So what happens when someone changes that contract? Some changes are safe, and some break everything." 6 to 7: "The best defense against accidental breakage is TypeScript — make the compiler enforce the contract." 7 to 8: "We have been looking at individual field definitions, but some field groups show up on every content type. That is where Global Fields come in." 8 to 9: "Global Fields are powerful, but they are not always the right tool — here is how to decide." 9 to 10: "Now let us talk about the trickiest field type: rich text. Specifically, the JSON Rich Text Editor." 10 to 11: "The real power of the JSON RTE is not just formatting — it is embedding other entries and assets right inside the text." 11 to 12: "And if the built-in toolbar is not enough, you can extend the JSON RTE with custom plugins." Closing to Video 4: "We have covered how to model domain concepts, lock in API contracts, and handle rich text. In the next video, we will connect these content types together with references, modular blocks, and taxonomies — the relationship layer that makes your content model actually work." ## Common Mistakes to Call Out 1. Recreating page layouts as content types. Building a "Homepage" content type with fields for hero\_section, featured\_products\_carousel, and newsletter\_signup locks content into a single layout and throws away all reuse benefits. Use Modular Blocks or references to compose pages from independent content pieces. 2. Storing structured data inside rich text fields. Putting the product line description inside a JSON RTE as formatted text makes it impossible to query by product line, filter products, or generate collection pages. If data needs to be queried or reused independently, it belongs in its own content type with discrete fields. 3. Duplicating content instead of referencing it. Copying the product line name and description into every product entry creates maintenance burden and guarantees inconsistency. Use Reference fields to point to a single Product Line entry. 4. Treating field UIDs as internal details. Field UIDs are public API field names. Choosing a UID like f1 or temp\_field makes the API response unreadable and forces frontend developers to guess. Use meaningful, stable UIDs from the start. 5. Changing field types without coordinating with frontend teams. Converting a Date field to Single Line Text changes the API output from an ISO 8601 string to freeform text. The frontend date formatter breaks. Treat type changes as a contract renegotiation. 6. Ignoring optional fields in frontend code. When a new field is added, existing entries do not have a value for it. Components that assume every field has a value crash with "Cannot read property of undefined." Always use optional chaining and null checks. 7. Creating global fields for data that should be references. A "Featured Product Line" global field with line\_title, line\_description, and line\_image embedded in every Product creates data duplication. That data belongs in a Product Line content type with Reference fields. Global fields share structure, not content. 8. Modifying global fields without checking downstream impact. Removing a field from a global field used by 12 content types simultaneously breaks the API contract for all 12. The blast radius is proportional to reuse. Always audit usage before editing a global field. 9. Not handling embedded entries in the frontend renderer. When editors embed entries in a JSON RTE, the API response contains reference nodes. If the renderer does not handle the reference node type, those entries silently disappear from the output. 10. Forgetting include\_embedded\_items\[\] in the API call. Without this parameter, embedded entry references contain only UIDs, not actual data. Embedded content vanishes from the rendered page with no error — it just disappears. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 3 — Structured Content and API Contracts** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 05 — Video Production Plan : Video 4 — Composition, Query Performance, and Modeling in Practice #### Lesson text # Video 4 — Composition, Query Performance, and Modeling in Practice Attribute Details Course 2 (Content Modeling), Modules 2.2 and 2.3 Covers Lessons 2.2.1, 2.2.2, 2.2.3, 2.3.1, 2.3.2, 2.3.3, 2.3.4, 2.3.5 Priority Core Length 20-28 min Format Live model review using the Veda scenario Status Not started ## Why This Video Matters This is where modeling theory becomes real-world decision making. Learners see how to translate business requirements into content types and how to audit and improve existing models. ## Outline 1. References vs Modular Blocks: when to use each * References: link to independent entries (Product references a Category) * Modular Blocks: composable, inline content sections (hero, feature grid, testimonial) 2. Show a reference field and a modular blocks field in the editor, then compare their API output 3. Taxonomy, tags, and classification: organizing content beyond references 4. Query performance: payload size, include depth tradeoffs, keeping queries efficient 5. Start with a Veda business requirement and translate it into content types step by step 6. Auditing a messy content model: identify duplicated fields, missing references, unclear naming 7. Model sprawl: what 50 content types that should be 15 looks like, how to prevent it 8. Modeling for multiple channels: same content, different presentations 9. Localization strategy: localized fields vs localized entries, fallback behavior 10. Governance frameworks: naming conventions, review processes, documentation standards ## Key Lines "Many performance problems begin as modeling problems." "The cleanest editor experience and the cleanest API are often connected." "A good content model scales with your team. A bad one scales against it." ## Detailed Talking Points ### 1\. References vs Modular Blocks: when to use each * References create pointers to independent entries. A Product references a Category. The Category lives on its own, has its own publish state, its own URL in the Management API. Update the Category once, every Product that references it picks up the change. * Modular Blocks are inline composable sections: hero, feature grid, testimonial strip, CTA. The data lives inside the parent entry. No separate entry, no separate lifecycle. * The decision rule: if the content is reused across multiple entries and has its own editorial lifecycle, use a reference. If the content belongs to one page and nobody would ever browse or search for it independently, use a modular block. * Common mistake: creating a separate hero\_banner content type and referencing it from a page when that hero only ever appears on one page. That is unnecessary indirection. Use a modular block instead. * Opposite mistake: embedding author data as a modular block inside articles. Now every article carries its own copy of the author bio. Updating the bio means editing every article. References solve this. * Extensions (custom fields) exist too, but they solve a different problem: specialized editorial UI like color pickers or third-party lookups. Higher build cost, only reach for them when native fields cannot handle the UX requirement. ### 2\. Show a reference field and a modular blocks field in the editor, then compare their API output * Open a Veda page entry that has both a reference field (e.g., testimonials) and a modular blocks field (e.g., page\_sections). Show them side by side in the editor. * Reference field: editor picks from existing entries using an entry picker. The referenced entries exist independently. * Modular blocks field: editor adds, removes, and reorders blocks inline. Block data is tightly coupled to this entry. * Fetch the entry via the Delivery API without include\[\]. Show that reference fields return only UIDs and \_content\_type\_uid -- not the actual content. Modular blocks return full inline data with no extra resolution needed. * Add ?include\[\]=testimonials to the query. Now the referenced entries resolve inline. Stress that this is an explicit step developers must remember. * Show the JSON side by side: references produce separate entry payloads nested under the reference key; modular blocks produce an array of objects keyed by block type. ### 3\. Taxonomy, tags, and classification: organizing content beyond references * Contentstack has three classification mechanisms: Taxonomy (governed, hierarchical, cross-content-type), Tags (freeform string arrays, zero setup), and reference-based categorization (categories as full content entries). * Taxonomy: centrally managed under the Taxonomy section in the stack. You define terms in a hierarchy. Editors pick from controlled vocabularies. Queryable across content types with taxonomies.product\_line syntax. * Tags: easy to add, impossible to govern. After six months you get "AI", "A.I.", "ai", "artificial-intelligence" all meaning the same thing. Queries miss content. * Reference-based categorization: best when the category itself is a rich content entity with its own page, description, and metadata. But querying across content types requires separate API calls per type. * Decision framework: use taxonomies for governed facets that power navigation and filtering, tags for informal internal labels, references for content-rich categories with their own pages. * For Veda: product\_line and category taxonomies enable cross-content-type queries like "show me everything in Digital Dawn" with a single API call. ### 4\. Query performance: payload size, include depth tradeoffs, keeping queries efficient * Every content model is also a query contract. The fields, references, and modular blocks you define determine the size, speed, and cost of every API response. * Include depth: default is 0 (references return as UIDs only). Each level of include\[\] adds latency and payload size. One level might be 80ms. Two levels might be 200ms. Three might exceed 400ms. * Max useful depth is usually 2-3. If your model requires more, that is a signal to flatten the model, not work around the depth limit. * Payload budgets: aim for individual entry responses under 50KB, list queries under 200KB. Rich text fields in referenced entries, modular blocks with many instances, and multi-reference fields with large arrays are the main bloat drivers. * Use only\[BASE\]\[\] for list views to return only the fields the UI needs. A product card showing title, thumbnail, and price does not need the full rich text description. * Normalized vs denormalized: pure normalization means many references and slow queries. Pure denormalization means duplicate data and update pain. The practical middle ground: normalize entities with independent lifecycle, denormalize display-only data that rarely changes. * Worked example: a naive product model with 5 levels of reference depth resolves 28 entries per request. Flattened to 2 levels, it resolves 7 entries. Same data, fraction of the cost. ### 5\. Start with a Veda business requirement and translate it into content types step by step * Start with the brief: "Veda wants to add gift sets that bundle 2-4 products, with a name, description, hero image, and optional gift message. Gift sets appear in Digital Dawn and Charmed Revival product lines. Support English and Spanish." * Step 1: identify entities. Read the brief, underline nouns that have their own identity and lifecycle. Gift Set, Product (already exists), Product Line (already exists). Not "Gift Set Page" -- that is presentation. * Step 2: determine relationships. Gift Set contains Products (many-to-many reference). Gift Set appears in Product Lines (many-to-many reference). * Step 3: define fields. Gift Set gets title (mandatory, unique), URL, description (JSON RTE), hero image, gift message, products (multi-reference, mandatory), product\_line (multi-reference). * Step 4: decide what NOT to model. Inventory, cart state, pricing -- those belong in the commerce system, not the CMS. Draw a clear boundary between editorial content and transactional data. * Step 5: validate with real entries and API responses before committing. Create 2-3 entries with real content, fetch via the Delivery API, confirm the JSON matches what the frontend expects. ### 6\. Auditing a messy content model: identify duplicated fields, missing references, unclear naming * Audit when you see signals: 40+ field content types, fields named \*\_v2 or temp\_\*, editors consistently skipping fields, developers getting API responses full of unused keys. * Red flags: content types with 40+ fields, fields empty across 90% of entries, confusing names like cta\_link\_2 or misc\_data, reference chains 4+ levels deep, dual-purpose content types. * Step 1: export schemas via the Management API, sort by field count. Highest field counts are your first audit targets. * Step 2: analyze field population rates. Fields with less than 10% population are candidates for removal. * Step 3: interview editors. "Walk me through creating an entry. Where do you pause? Which fields do you skip?" * Step 4: map API consumers. Which frontends read which fields? Fields that no consumer reads and no editor populates are dead weight. * The 47-field Product example: split into Product (core, 10-12 fields), Product Specs (referenced), SEO Metadata (Global Field). Inventory and pricing fields removed from the CMS entirely. * UID changes are coordinated migrations, not casual renames. Changing a UID breaks every API consumer that references the old key. ### 7\. Model sprawl: what 50 content types that should be 15 looks like, how to prevent it * Model sprawl: too many content types, each too small to justify its existence, connected by deep reference chains. * Warning signs: more content types than entries for some types (a CallToAction type with 3 entries), editors cannot find where to create content (35+ options in the dropdown), assembling one page requires touching 6+ content types. * The "one content type per component" anti-pattern: mapping every React component to its own content type. A HeroBanner with 4 fields, a FeatureCard with 3 fields, a StatCounter with 2 fields. None of these are content entities. They are field groups masquerading as content types. * The fix: use Modular Blocks for component-level structures, Global Fields for reusable field groups, standalone content types only for entities with independent lifecycle. * The rule of three: do not extract a reusable pattern until you have three concrete instances. One testimonial page does not justify a Testimonial content type. * Real example: a startup with 35 content types and 200 entries consolidated to 9 content types. Same website, same content, fraction of the complexity. * Healthy ratios: a marketing site needs 5-10 types, a corporate site 10-20, a media platform 8-15. 35 types with 200 entries is a red flag. ### 8\. Modeling for multiple channels: same content, different presentations * Core principle: structure content for meaning, not for presentation. Channel-specific rendering is the frontend's job. * Channel-neutral content: structured JSON RTE, a single high-res image (use Image Delivery API transforms for sizing), key\_features as an array. Works for web, mobile app, voice assistant, email. * Channel-coupled content (anti-pattern): web\_hero\_html, mobile\_short\_description, email\_preview\_text, kiosk\_display\_mode. Every new channel requires new fields. Every copy change requires updating multiple fields. * Practical rules: store content as structured data not markup, use Image Delivery API for responsive images, keep field names channel-agnostic (short\_description not mobile\_description), use include\[\] strategically per consumer. ### 9\. Localization strategy: localized fields vs localized entries, fallback behavior * Localization operates at three levels: stack-level language configuration, field-level localization settings, and entry-level data. * Field-level decision: mark fields as non-localizable by default. Only opt in for text that editors actually translate. Title, description, CTA labels, alt text -- localize these. Dates, SKUs, reference fields, booleans -- keep universal. * Common mistake: making a reference field localizable. Now the French version of a product silently points to a different category than the English version. Nothing in the UI flags the inconsistency. * Fallback hierarchy: design it before launch. fr-ca falls back to fr-fr, which falls back to en-us. This lets you launch with only base-language content and progressively translate. * Locale-specific publishing: editors switch locale in the entry editor, translate localizable fields, and publish the localized version independently. The Delivery API returns the best available version per field based on the fallback chain. * Prioritize translations by fallback usefulness: Japanese first (fallback to English is least useful for Japanese readers), then French, then regional variants. ### 10\. Governance frameworks: naming conventions, review processes, documentation standards * Naming conventions are the highest-impact, lowest-cost governance tool. Content type UIDs: snake\_case (blog\_post, not blogPost or bp). Field UIDs: snake\_case, short but unambiguous. Display names: human-readable for editors. * Bad UIDs: blogPost (camelCase), bp (cryptic), content\_blog\_post\_v2 (version numbers signal migration debt), page\_component\_hero\_banner\_module (over-qualified). * Field descriptions: every field should have a populated description. "Page title shown in browser tabs and search results. Keep under 60 characters." costs 30 seconds to write, saves hours of confusion. * Roles and permissions: restrict content type modification to Admin roles. Give editors Content Manager roles scoped to their content types. This prevents accidental schema changes. * Lightweight review process: maintain a decision log for structural changes. Three questions per entry: what changed, why, who decided. Not a formal approval workflow -- a log. Takes 2 minutes. * Threshold: adding an optional field -- just do it and log. Creating a new content type, removing a field UID, changing a reference target -- discuss first, then log. * Use built-in guardrails: mandatory fields for minimum viable entries, unique constraints for identifiers, regex validation for slugs and SKUs, Select fields instead of freeform text for known value sets. ## Screen: What to Show Outline Item / Segment What to Show on Screen / Instructions Outline items 1-2 (References vs Modular Blocks) Open the Veda stack in Contentstack. Navigate to a Page content type that has both a reference field (e.g.,  testimonials  referencing the Testimonial content type) and a modular blocks field (e.g.,  page\_sections ). Show the content type schema view first: point out the reference field config (which content types it can reference, single vs multi) and the modular blocks config (block type definitions with their inline fields). Switch to an entry. Show the reference field picker UI (searching and selecting existing entries) vs the modular blocks composer (adding blocks, reordering with drag-and-drop). Open a terminal or API client (Postman, Insomnia, or curl). Fetch the entry without  include\[\]  -- show the raw UIDs for references. Then add  ?include\[\]=testimonials  and show the resolved data. Side-by-side the two JSON responses. Show the modular blocks portion of the response -- full inline data, no extra parameters needed. Outline item 3 (Taxonomy, tags, classification) Navigate to the Taxonomy section in the left nav of Contentstack. Show the  product\_line  taxonomy with its terms (Digital Dawn, Urban Armor, etc.). Open a Product entry and show the taxonomy field where editors assign terms from the controlled vocabulary. In the terminal, run a taxonomy query:  ?query={"taxonomies.product\_line":{"$in":\["digital\_dawn"\]}}  -- show results spanning content types. Contrast with a freeform tags field on another entry. Type a few inconsistent tags to illustrate the governance problem. Outline item 4 (Query performance) Show a product entry with deep references: product -> product\_line -> related\_products -> their product\_lines. Diagram or whiteboard the reference tree. Fetch the entry with all includes and show the response time and payload size in the API client. Then fetch with  only\[BASE\]\[\]=title&only\[BASE\]\[\]=slug&only\[BASE\]\[\]=thumbnail  -- show the dramatically smaller response. Optionally show a before/after payload size comparison on screen (e.g., 85KB vs 4KB for a list view). Outline item 5 (Translating requirements) Put the Veda gift set brief on screen (text overlay or slide). Walk through underlining the nouns that become entities. Whiteboard or diagram the entity-relationship map: Gift Set -> Products, Gift Set -> Product Lines. Switch to Contentstack, create the Gift Set content type live (or show a pre-built one). Walk through each field and explain why it exists. Create a sample Gift Set entry with real Veda product names. Fetch it via the API and show the JSON. Outline item 6 (Auditing) Show a deliberately messy content type schema (pre-built for the video): 40+ fields, names like  banner\_v2 ,  temp\_promo ,  old\_description . Scroll through it in the content type builder. Run the Management API curl command to export schema and pipe through  jq  to show field counts per content type. Show a spreadsheet or table with field population rates (percentage of entries where each field has data). Highlight fields at 5-10% population. Outline item 7 (Model sprawl) Show a stack sidebar with 30+ content types listed. Scroll through it. Point out types with 2-3 entries. Show the "before" model: 35 types, 200 entries. Then show the "after": 9 types, same content. Use a slide or diagram with both side by side. Outline items 8-9 (Channels and localization) Show a channel-neutral Product entry: structured JSON RTE, single hero image, key\_features array. Show the Image Delivery API in action: append  ?width=400&format=webp  to an image URL, show the resized result. Switch locales in the entry editor. Show how non-localizable fields (SKU, dates) are read-only in the localized view. Translate a localizable field (product name) into Spanish. Show the locale fallback config under Settings > Languages. Diagram the fallback hierarchy. Outline item 10 (Governance) Show the Roles & Permissions screen in Contentstack. Walk through Admin vs Content Manager role differences. Show a well-documented content type: populated Description field, field descriptions with clear guidance, regex validation on a slug field. Contrast with an undocumented content type: empty descriptions, cryptic field names. Show a sample decision log (Markdown file in the repo or a Notion page). ## Veda Scenario Thread The entire video uses Veda as the connective tissue: 1. **References vs Modular Blocks:** Veda's Product references Category and Product Line (independent entities, shared across products). Veda's landing pages use modular blocks for hero, feature grid, and CTA sections (page-specific, no reuse). 2. **API comparison:** Fetch a Veda product page. Show testimonials as unresolved UIDs, then resolved with include\[\]. Show page\_sections as inline modular block data. 3. **Taxonomy**: Veda classifies products by product\_line (Digital Dawn, Urban Armor) and category (Earrings, Bracelets) using taxonomies. Show a cross-content-type query: "everything in Digital Dawn" returns products, product lines, and pages in one call. 4. **Query performance:** The Veda product detail page resolves product\_line, category, and 5 related products. At two levels deep, that is 17 entries per request. Show how flattening (inline category\_path, capped related\_products) drops it to 7 entries. 5. **Translating requirements:** Take the Veda gift set brief live. Walk from business paragraph to entity identification to content type creation to sample entry to API response. 6. **Auditing:** Show a hypothetical "inherited Veda stack" with model debt: a 47-field Product type, fields named promo\_banner\_v2, empty legacy\_tagline fields. Audit it on screen. 7. **Model sprawl:** Show what happens if someone mapped every Veda page component to its own content type: HeroBanner, FeatureCard, TestimonialSlide, StatCounter. 30+ types, 150 entries. Consolidate to the actual Veda model with modular blocks. 8. **Channels:** Veda serves the same product data to web (full layout) and mobile app (card view). Same entry, different only\[BASE\]\[\] projections and include\[\] depths per consumer. 9. **Localization:** Veda launches in English and Spanish. product\_name and description are localizable. SKU, price, release\_date, reference fields are not. Show the fallback: es-mx falls back to es-es, which falls back to en-us. 10. **Governance:** Veda's naming conventions: product, product\_line, gift\_set (snake\_case UIDs). Field descriptions populated. Content type descriptions state ownership and usage. Decision log records why gift\_set was added. ## Transitions 1 to 2: "Now that you know the rules, let me show you what this actually looks like in the editor and the API." 2 to 3: "References and modular blocks handle composition -- but classification is a different problem entirely." 3 to 4: "Every classification and composition choice has a cost, and that cost shows up in your API responses." 4 to 5: "Knowing the performance tradeoffs is useful, but let me show you how to apply all of this from scratch with a real business requirement." 5 to 6: "That was a greenfield model -- now let me show you what happens when you inherit someone else's model and need to fix it." 6 to 7: "Auditing catches bloated content types, but the opposite problem -- too many tiny content types -- is just as damaging." 7 to 8: "Once the model is clean, make sure it works for every channel, not just the website." 8 to 9: "Multi-channel is about delivery variation -- localization is about language variation, and the modeling decisions are just as important." 9 to 10: "A good model degrades without governance -- naming conventions, role restrictions, and a lightweight decision log keep it healthy over time." Closing to Video 5: "You now know how to compose, query, audit, and govern content models. In Video 5, we shift to the API layer -- how to actually fetch, filter, and deliver this content to your frontends." ## Common Mistakes to Call Out 1. **Using references for content that is never reused.** A separate hero\_banner content type referenced from one page adds lifecycle overhead, publish-state complexity, and an extra include\[\] for zero reuse benefit. Use a modular block. 2. **Using modular blocks for content that needs independent lifecycle.** Embedding author bios as modular blocks means every article carries its own copy. Updating an author bio requires editing every article individually. 3. **Forgetting** **include\[\]** **on reference fields.** The frontend receives UIDs instead of content. This is the single most common "why is my data missing" question from new Contentstack developers. 4. **Resolving all references on every query.** Fetching articles with include\[\]=author&include\[\]=category&include\[\]=related\_articles&include\[\]=tags when the list view only shows title and date. Use only\[BASE\]\[\] for list views. 5. **Ignoring payload size until production.** Development datasets are small. A 2,000-entry catalog with rich text and images exposes every over-fetching pattern. Test with realistic data volumes early. 6. **Modeling deep hierarchies as chained references.** Category trees as category -> parent -> grandparent -> root create unbounded reference depth. Store the hierarchy as a denormalized path field and use a single reference to the leaf. 7. **Using freeform tags for user-facing navigation.** After six months: "AI", "A.I.", "ai", "artificial-intelligence" all meaning the same thing. If classification drives navigation or filtering, use taxonomies. 8. **Mapping frontend components 1:1 to content types.** Every React component gets its own content type. 35 types, 200 entries. Editors spend more time navigating the model than writing content. 9. **Localizing fields that should be universal.** Making a reference field or date field localizable means the French version silently points to a different category than English. Default to non-localizable, opt in per field. 10. **No naming conventions.** Five developers create content types with five different naming styles. Onboarding a new developer six months later requires archaeology instead of reading documentation. 11. **Skipping the relationship mapping step.** Jumping to field definitions without mapping entity relationships produces content types that either duplicate data or miss connections. 12. **Treating the content model as final.** A content model is a living artifact. Build with the expectation of iteration, not perfection. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 4 — Composition, Query Performance, and Modeling in Practice** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 06 — Video Production Plan : Video 5 — API Architecture, Authentication, and Query Surface Choice #### Lesson text # Video 5 — API Architecture, Authentication, and Query Surface Choice Attribute Details Course 3 (APIs and Developer Tooling), Module 3.1 Covers Lessons 3.1.1, 3.1.2, 3.1.3, 3.1.4, 3.1.5 Priority Critical Length 18-25 min Format Screencast (Postman/terminal + slides for architecture diagrams) Status Not started ## Why This Video Matters This clarifies the boundaries developers most often confuse. Most API mistakes are boundary mistakes, not syntax mistakes. ## Outline 1. Two APIs, two jobs: Delivery API (read-only, CDN-backed, fast) vs Management API (CRUD, authenticated, for tooling) 2. When to use which: frontend always uses Delivery; CI/CD, migrations, and admin scripts use Management 3. Preview vs published delivery concerns 4. Regions and clouds: NA, EU, Azure NA, Azure EU — each has different base URLs 5. Show where to find the correct base URL for your stack 6. REST vs GraphQL tradeoffs: REST for simple queries and full SDK support; GraphQL for precise field selection and reducing over-fetching 7. Show the same query in REST and GraphQL side-by-side, compare payload sizes 8. Authentication: Delivery Tokens (environment-scoped, read-only) vs Management Tokens vs OAuth 9. Token placement and credential scoping — demonstrate creating and using each token type 10. Rate limits: know the limits, handle 429 responses gracefully, implement backoff 11. Error codes walkthrough: common errors (401, 404, 422, 429) and what to do about each ## Key Lines "Most API mistakes are boundary mistakes, not syntax mistakes." "Choose the API by intent, not by convenience." "If a token ends up in the wrong runtime, that is an architecture issue, not a documentation issue." ## Detailed Talking Points ### 1\. Two APIs, two jobs * Contentstack has two separate API planes: the Content Delivery API (CDA) and the Content Management API (CMA). They exist for fundamentally different reasons. * CDA is read-only, CDN-backed, optimized for high-volume frontend traffic. It only returns published content. * CMA handles CRUD operations: creating entries, updating content types, managing workflows, publishing, branch administration. * These are two different reliability planes. CDA is designed for many reads, low latency, aggressive caching. CMA is designed for fewer requests, higher privilege, explicit auditability. * Different token types protect each plane. Delivery tokens are environment-scoped and read-only. Management tokens are stack-level and read-write. * Different blast radius: if a delivery token leaks, an attacker can read published content. If a management token leaks, an attacker can modify or delete your entire stack. * Think of it as: delivery plane vs control plane. Keep them separated in your codebase, your token strategy, and your mental model. ### 2\. When to use which: the decision framework * Do not choose the API by convenience or by what returns results during local dev. Choose by intent. * Five-question decision sequence: (1) What is the intent -- render or manage? (2) What data state -- published or draft? (3) Where does this call run -- browser/edge or backend? (4) What token can safely exist in this runtime? (5) What happens if this endpoint is abused? * If the intent is rendering published content for users: CDA. Always. * If the intent is content operations -- creating, updating, deleting, publishing, workflow actions: CMA. Only in trusted backends. * If your answers to these five questions mix two intent classes in one code path, split the design before writing code. * CMA has GET endpoints. That does not make them delivery endpoints. Classify by intent, not HTTP verb. * Common mistake: using CMA reads in frontend code because "it works locally." It does work -- until you ship a management token to the browser. ### 3\. Preview vs published delivery concerns * CDA returns only published content for a given environment. If an editor saves a draft, CDA will not reflect it. * For draft or preview content, use the Preview API with preview tokens -- a separate retrieval context. * Preview tokens are still read-path credentials. They should never grant management capabilities. * In Veda's case: the storefront uses CDA for production traffic. The editorial preview experience uses the Preview API so editors see unpublished changes. ### 4\. Regions and clouds * Your stack's region is locked at creation. It determines every API base URL your code targets. You cannot change it later. * Contentstack operates across seven regions on three cloud providers: AWS (NA, EU, AU), Azure (NA, EU), GCP (NA, EU). * Each region has its own set of base URLs for CDA, CMA, GraphQL, Preview, Assets, and all platform services. * AWS NA is the "default" -- it uses the .io TLD (cdn.contentstack.io). Every other region uses .com with a prefix (eu-cdn.contentstack.com, azure-na-cdn.contentstack.com). * The .io vs .com TLD difference is a common copy-paste error. If you switch from NA to EU and only change the prefix but keep .io, your requests will fail silently. * Reasons for region choice: data residency (GDPR), latency, cloud provider alignment with existing infrastructure. ### 5\. Finding the correct base URL * Dashboard: Settings > Stack shows the region. * Browser URL gives a hint: eu-app.contentstack.com means AWS EU, azure-na-app.contentstack.com means Azure NA. * Use the SDK's built-in region constants (Contentstack.Region.EU, Contentstack.Region.AZURE\_NA, etc.) -- the SDK constructs correct endpoints automatically. * For endpoints beyond the Delivery SDK (Preview host, Application host for Live Preview), use the @timbenniks/contentstack-endpoints package or reference the official regions data at artifacts.contentstack.com/regions.json. * Quick diagnostic: if credentials are correct but you get 401 or empty results, test the same request with curl against different region base URLs. One returns 200, the other returns 401. The 200 one is your actual region. ### 6\. REST vs GraphQL tradeoffs * Both REST CDA and GraphQL CDA are read-only, use the same delivery tokens, return only published content, and sit behind CDN infrastructure. * REST strengths: simple and predictable URLs, strong CDN caching (GET requests are inherently cacheable), mature SDK support, include\[\] for reference resolution, rich query operators ($in, $gt, $regex, etc.). * REST limitation: over-fetching. You get all fields even if you only need two. Fixed response shape. Multiple round trips for unrelated content types. * GraphQL strengths: request exactly the fields you need, fetch from multiple content types in a single query, schema introspection, type safety with codegen. * GraphQL limitations: no mutations (all writes go through REST CMA), query complexity limits for deeply nested references, POST-based requests are harder to cache at CDN edge, SDK support is primarily REST-oriented. * GraphQL does not support the SDK include\[\] syntax for references. It uses the Relay-style Connection pattern instead. * Neither is "better." Choose per-query based on actual needs: payload size sensitivity, query complexity, caching requirements, team familiarity. ### 7\. Same query in REST and GraphQL side-by-side * Show fetching blog posts with author references in REST: GET /v3/content\_types/blog\_post/entries?environment=production&include\[\]=author with api\_key and access\_token headers. * Show the same query in GraphQL: a query selecting only title, url, and authorConnection with specific fields. * Compare the response payloads. REST returns every field on blog\_post and author. GraphQL returns exactly what you asked for. * Point out the Connection syntax in GraphQL for references and assets -- this is Contentstack-specific and catches people off guard. * Call out that both use the same delivery token. The auth model is identical. The query model is different. ### 8\. Authentication: token types and their roles * Three credential types to know: Delivery Tokens, Management Tokens, and OAuth tokens. * Delivery Tokens: environment-scoped, read-only, safe for client-side code. They can only read published content for one specific environment. * Management Tokens: stack-level, read-write, never expose to clients. They can create, update, delete entries, modify content types, manage workflows. If this token leaks, your stack is compromised. * OAuth: used for Contentstack Apps. Enables user-context-aware operations with consent flows. * Design your credential model around four questions: Who is the actor? What plane is accessed? What is the minimum scope? How will this credential be rotated? * Token selection should be the output of this security model, not the starting point. ### 9\. Token placement and credential scoping * Show creating a delivery token in the dashboard: Settings > Tokens > Delivery Tokens. Note it is scoped to a specific environment. * Show creating a management token: Settings > Tokens > Management Tokens. Note the stack-level scope and permission configuration. * Code example: separate deliveryClient and managementClient configs in api-clients.ts. The delivery client uses cdn.contentstack.io with access\_token. The management client uses api.contentstack.io with authorization. * Architectural rule: frontend request handlers can import deliveryClient only. CMA calls stay in trusted back-office services. Enforce this with linter rules or module boundaries. * Smell test: if revoking one token would break many unrelated systems, your security boundary is too broad. One credential per service responsibility. ### 10\. Rate limits: know them, respect them, handle 429 * CDA rate limits are generous (paid plans: ~200 req/s) because delivery traffic is cacheable and read-only. * CMA rate limits are tighter (~10 req/s default) because it handles write operations. This is where rate limiting becomes a daily concern during migrations, bulk publishes, and automated workflows. * Read X-RateLimit-Remaining on every response -- not just errors. Proactively throttle before hitting the wall. * When you get a 429: exponential backoff with jitter. Formula: delay = min(baseDelay \* 2^attempt + random(0, jitterMax), maxDelay). * Jitter is not optional. Without it, concurrent clients synchronize their retries and create a thundering herd -- all retrying at the same instant, re-triggering the overload. * CMA write retries have an idempotency danger: if a POST times out but the server processed it, retrying creates a duplicate entry. Use UID-based updates when possible, or check for existence before retrying creates. ### 11\. Error codes walkthrough * 401 Unauthorized: wrong or missing token. Could also mean correct token but wrong region endpoint. Do not retry -- fix the credential or region. * 404 Not Found: wrong content type UID, wrong entry UID, or malformed API path. Could also mean correct UID but wrong region. One edge case: brief 404 right after publishing due to propagation delay. * 412 Precondition Failed: version conflict on CMA entry update, or region/credential mismatch. For version conflicts: re-fetch the entry, get the current version, merge your changes, resubmit. * 422 Unprocessable Entity: your JSON is syntactically valid but semantically wrong. Missing required fields, invalid reference UIDs, validation rule violations. Do not retry -- fix the payload. * 429 Too Many Requests: rate limited. Retry with exponential backoff + jitter. * Classify before retrying. 429 and 500 are retryable. 401, 403, 404, and 422 are permanent. 412 is retryable but requires a re-fetch first. Retrying permanent errors wastes rate limit quota with zero chance of success. ## Screen: What to Show Outline item Screen instructions Opening (Outline items 1-3) Slide: architecture diagram showing two planes side-by-side. Left: "Delivery Plane" (CDA, GraphQL CDA, Preview API) with arrows to browser/edge/SSR. Right: "Control Plane" (CMA) with arrows to CI/CD, admin scripts, backend services. Code editor: show  api-clients.ts  with the  deliveryClient  and  managementClient  separation. Highlight the different hosts ( cdn.contentstack.io  vs  api.contentstack.io ) and different auth headers ( access\_token  vs  authorization ). Slide: decision framework -- the five-question flowchart. Walk through each question with Veda's storefront as the example.  Regions (Outline items 4-5) Contentstack dashboard: navigate to Settings > Stack to show the region indicator. Slide: regions table showing AWS NA, AWS EU, Azure NA, Azure EU, GCP NA with their CDA and CMA base URLs. Highlight the  .io  vs  .com  TLD difference for AWS NA. Terminal: run the  curl  diagnostic -- hit  cdn.contentstack.io  and  eu-cdn.contentstack.com  with the same credentials, show one returns 200 and the other returns 401. Code editor: show SDK region configuration with  Contentstack.Region.EU  and the  @timbenniks/contentstack-endpoints  helper.  REST vs GraphQL (Outline items 6-7) Postman or terminal: execute the REST query for blog posts with  include\[\]=author . Show the full response payload with all fields. GraphQL playground or Postman: execute the equivalent GraphQL query requesting only  title ,  url , and author  title  +  bio . Show the trimmed response. Split screen: place both response payloads side-by-side. Highlight the size difference. Code editor: show the GraphQL  Connection  pattern for references ( authorConnection { edges { node { ... on Author { title } } } } ).  Authentication (Outline items 8-9) Contentstack dashboard: Settings > Tokens. Create a delivery token -- show the environment scope. Create a management token -- show the stack-level permissions. Code editor: show the  getReadHeaders()  helper that returns different headers for  "published"  vs  "preview"  modes, plus the  managementHeaders  constant. Highlight the comment: "managementHeaders never leaves trusted server code." Terminal: make a CDA request with a delivery token (succeeds). Make the same request with a management token against CDA (fails or returns differently). Show the boundary.  Rate Limits and Errors (Outline items 10-11) Code editor: show the  resilientFetch  function with error classification ( classifyError ), exponential backoff calculation, and rate limit header logging. Terminal: trigger a 429 intentionally (rapid-fire CMA requests in a loop). Show the  X-RateLimit-Remaining  header counting down to zero, then the 429 response. Slide: error code reference table -- status code, retryable yes/no, what to do. Keep it on screen while walking through each code. Terminal: show a 401 from a region mismatch, a 422 from a malformed payload, and a 404 from a wrong content type UID. For each, show the JSON error body and explain the fix. ## Veda Scenario Thread Veda is a fashion and lifestyle brand building a headless storefront on Contentstack. Use Veda throughout this video to ground every concept in a real project context. * **Two APIs, two jobs:** Veda's Next.js storefront fetches product pages, collection listings, and editorial content through CDA. A separate backend service handles content migrations, automated tagging, and bulk publishing through CMA. Two codebases, two token types, two reliability contracts. * **Decision framework:** walk through the five questions using Veda's "Related Products" strip. Intent: render published products for shoppers (CDA). Data state: published (CDA). Runtime: edge-rendered storefront (no management creds). Token: delivery token safe in browser. Blast radius of misuse: reads only, no data integrity risk. * **Regions:** Veda's primary market is Europe. Their stack is on AWS EU. Every base URL uses the eu- prefix. When an American contractor onboarded and copied cdn.contentstack.io from a tutorial, requests returned empty results with no error message -- a classic region mismatch. * **REST vs GraphQL:** Veda uses REST via the SDK for standard product detail pages (simple, cacheable, SDK handles includes). For the homepage -- which pulls hero content, featured collections, editorial picks, and navigation items from four content types -- they use a single GraphQL query to avoid four separate REST calls. * **Authentication:** Veda's delivery token is scoped to the production environment and is safe in the Next.js client bundle. The management token lives only in a backend service that runs nightly content sync jobs. When the marketing team asked for a "quick admin panel" in the storefront, the engineering team said no -- management tokens do not belong in client-facing code. * **Rate limits:** during Black Friday content preparation, Veda's ops team ran a migration script that bulk-published 2,000 product entries. At CMA's 10 req/s limit, the script started hitting 429s after the first batch. They added exponential backoff with jitter, read X-RateLimit-Remaining to throttle proactively, and completed the publish in 8 minutes instead of crashing in a retry storm. * **Error codes:** a junior developer on Veda's team got a 404 when querying a product entry that definitely existed. The UID was correct, the token was correct -- but the SDK was configured for Contentstack.Region.US instead of Contentstack.Region.EU. The entry did not exist in the NA region. Region mismatch masquerading as a missing resource. ## Transitions Item 1 to 2: "Now that you see these are two separate planes, the question becomes: how do you decide which one to use for any given integration?" Item 2 to 3: "The decision framework handles most cases cleanly, but there is one nuance worth calling out -- what about content that is not yet published?" Item 3 to 4: "Once you know which API plane you need, the next thing to get right is the base URL -- and that depends entirely on your stack's region." Item 4 to 5: "Knowing the regions exist is one thing -- let me show you exactly where to find yours and how to configure it." Item 5 to 6: "With the right endpoint locked in, you have one more architectural choice: do you query with REST or GraphQL?" Item 6 to 7: "Theory is useful, but seeing both side-by-side makes the tradeoff concrete." Item 7 to 8: "You have picked your API plane, your region, and your query surface -- now you need the credentials to actually make the call." Item 8 to 9: "Understanding token types is half the job. The other half is making sure each token only exists where it belongs." Item 9 to 10: "Your tokens are in place and your queries are running -- but what happens when you send too many too fast?" Item 10 to 11: "Rate limits are one kind of error. Let me walk you through every error code you are likely to see and exactly what each one means for your code." Closing to Video 6: "You now have the full picture of Contentstack's API surface: which plane to use, which region to target, which query format to choose, how to authenticate, and how to handle errors. In Video 6, we will put this into practice with the SDK, CLI tooling, and developer workflow patterns." ## Common Mistakes to Call Out 1. **Using CMA GET endpoints for frontend delivery.** It works locally. It returns data. But you are shipping a management token to the browser, getting no CDN caching, and mixing your reliability planes. Classify endpoints by intent, not by HTTP verb. 2. **Hardcoding base URLs instead of using SDK region constants.** Copy-pasting cdn.contentstack.io from a tutorial when your stack is on EU or Azure. The SDK has Contentstack.Region.EU for a reason -- use it. 3. **Confusing** **.io** **and** **.com** **TLDs. AWS NA uses** **contentstack.io****.** Every other region uses contentstack.com. Changing the prefix but keeping the wrong TLD produces silent failures. 4. **Choosing GraphQL to avoid learning REST query syntax.** GraphQL is not "better REST." If your queries are simple and the SDK handles them well, GraphQL adds complexity without benefit. 5. **Assuming GraphQL supports mutations.** GraphQL CDA is read-only. All writes, workflow changes, and admin actions require the REST-based CMA. Teams that architect write operations against GraphQL hit a wall. 6. **Shipping management tokens in client-side code.** This is not a documentation issue -- it is an architecture issue. Management credentials belong only in trusted backends. If a token ends up in the browser, the blast radius is your entire stack. 7. **Sharing one management token across many services.** If revoking that token breaks five unrelated systems, your security boundary is too broad. One credential per service responsibility. 8. **Retrying all errors uniformly.** Wrapping every API call in a generic retry loop that treats 422 and 429 identically. Invalid payloads (422) will never succeed on retry -- you are just burning rate limit quota. 9. **No jitter in retry backoff.** Fixed-delay retries across concurrent clients create a thundering herd. Every retry implementation must include randomness. 10. **Ignoring** **X-RateLimit-Remaining** **until you get a 429.** Read the header on every response. Throttle proactively before hitting the ceiling, not reactively after crashing through it. 11. **Assuming a 404 means the resource does not exist.** It might mean you are querying the wrong region. The API does not tell you "this resource exists in a different region" -- it just says "not found." ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 5 — API Architecture, Authentication, and Query Surface Choice** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 07 — Video Production Plan : Video 6 — Fetching and Rendering Content with the SDK #### Lesson text # Video 6 — Fetching and Rendering Content with the SDK Attribute Details Course 3 (APIs and Developer Tooling), Module 3.2 (lessons 1-2) Covers Lessons 3.2.1, 3.2.2 Priority Critical Length 15-22 min Format Screencast (code editor + browser) Status Not started ## Why This Video Matters This is the moment the platform becomes real for developers. Learners watch content move from Contentstack into application code. ## Outline 1. SDK initialization: setting up the JavaScript SDK with stack API key, delivery token, and environment 2. Stack client setup and configuration 3. Fetching entries by content type, UID, and URL 4. Query chaining: conditions, sorting, pagination 5. Live-code a few common queries against the Veda stack 6. References and includes: how to resolve referenced entries in a single query (include depth levels) 7. Localization in queries: fetching locale-specific content, fallback behavior 8. Rendering a realistic response shape in the frontend ## Key Lines "This is the moment the platform becomes real for developers." "You are not just fetching content. You are shaping how the app consumes it." "Understanding the response object makes everything else easier." ## Detailed Talking Points ### 1\. SDK initialization: setting up the JavaScript SDK with stack API key, delivery token, and environment * Install @contentstack/delivery-sdk (not the legacy contentstack package). This is the modern, TypeScript-first SDK with tree-shaking support. * Call Contentstack.stack() with four required values: apiKey, deliveryToken, environment, and region. * Show where each credential lives in the dashboard: API key in Settings > Stack, delivery token in Settings > Tokens > Delivery Tokens. * Emphasize that region must match the data center where the stack was created. Wrong region gives empty results or 401 with zero hint about the actual cause. * Delivery tokens are scoped to a specific environment. Token for staging does not work when environment is set to production. * The SDK does not throw on initialization if credentials are empty strings. The error surfaces on the first query as a cryptic 401 or 412. Validate at startup. * Optional: pass branch if the stack uses branches. Without it, the SDK queries the main branch. ### 2\. Stack client setup and configuration * Walk through a real stack instance in code. Show the import: import Contentstack from "@contentstack/delivery-sdk". * Show environment variables pattern: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY, etc. * Demonstrate Contentstack.Region.US vs Contentstack.Region.EU -- these are built-in constants, not arbitrary strings. * Mention branch configuration for teams doing parallel content development: branch: "feature-digital-dawn-v2". * Stress that this stack instance is reused across the entire app. You initialize once, query many times. ### 3\. Fetching entries by content type, UID, and URL * Show stack.contentType("product").entry().query().find() -- this fetches all entries of a content type. * Show stack.contentType("product").entry("blt\_matrix\_link\_001").fetch() -- single entry by UID. Returns the entry directly, not wrapped in an array. * Show fetching by URL with .equalTo("url", "/products/digital-dawn/matrix-link-bracelet") -- this drives most page rendering in frontend frameworks. * Explain the difference: find() returns { entries: \[\], count: number }, while fetch() returns the entry object directly. * Under the hood, these map to GET /v3/content\_types/product/entries and GET /v3/content\_types/product/entries/{uid}. * Fetching by UID is faster and more cache-friendly than querying with a filter when you already have the UID. ### 4\. Query chaining: conditions, sorting, pagination * Show .equalTo("category", "blt\_earrings\_category\_001") for simple equality filters. * Show .where("price", QueryOperation.IS\_GREATER\_THAN, 100) for comparison operators. Import QueryOperation from the SDK. * List available operators: IS\_LESS\_THAN, IS\_GREATER\_THAN, EQUALS, INCLUDES -- these map to Contentstack's $gt, $lt, $in, $nin, etc. * Pagination: .limit(10).skip(0) for page 1, .limit(10).skip(10) for page 2. Default max is 100 entries per request. * Sorting: .orderByAscending("price") or .orderByDescending("created\_at"). * Stress that all these chain before .find(). The query is built, then executed. ### 5\. Live-code a few common queries against the Veda stack * Query 1: All products, sorted by price ascending. Show the response shape in the console. * Query 2: Products above $200 using .where("price", QueryOperation.IS\_GREATER\_THAN, 200). * Query 3: Paginated product listing -- first 5 products, then next 5. Show skip and limit in action. * Query 4: Products filtered by URL slug for a single product detail page. * Keep each query short. Type it live, run it, show the console output. No slides. * Point out system fields in the response: uid, created\_at, updated\_at, locale, \_version. ### 6\. References and includes: how to resolve referenced entries in a single query (include depth levels) * Without includeReference(), reference fields return UID stubs: { uid: "blt...", \_content\_type\_uid: "product\_line" }. You get the pointer, not the data. * Chain .includeReference("product\_line") to resolve references inline. Multiple fields: chain multiple .includeReference() calls. * The parameter takes the reference _field UID_ on the parent content type, not the content type UID of the target. This trips people up. * Depth levels via dot notation: .includeReference("product\_line.products") resolves two levels deep. * Performance: depth 1 is standard and fast. Depth 2 is acceptable. Depth 3+ risks payload bloat and increased latency. Only include what the current view renders. * Show the include\_all shorthand via .addParams({ include\_all: true, include\_all\_depth: 2 }) -- useful for page-level queries but less efficient for listing pages. * Anti-pattern: including everything "just in case." Each unnecessary include adds latency and bytes. ### 7\. Localization in queries: fetching locale-specific content, fallback behavior * Add .locale("fr-fr") to any query to fetch content in a specific locale. * Without include\_fallback, untranslated fields come back as empty or null. Visitors see blank content. * Chain .includeFallback() to walk the fallback chain: fr-ca -> fr -> en-us (master locale). * When references and locale are combined, referenced entries resolve in the same locale automatically. No need to specify locale per reference. * Gotcha: if a referenced entry does not exist in the requested locale and has no fallback, it may be excluded entirely from the response. Test locale coverage across content types. * Show publish\_details on the entry to determine which locale the content actually came from. ### 8\. Rendering a realistic response shape in the frontend * Map the SDK response to component props. Show a Product component receiving title, price, short\_description, product\_line\[0\].title. * Handle null fields defensively. Not every entry has every field filled in, especially with partial localization. * Use TypeScript generics on find() and fetch(): query.find() gives typed result.entries as Product\[\]. * Define types matching the content type schema. Reference the kickstart-veda lib/types.ts as a real-world example. * Show the before/after: untyped response with any vs typed response with autocomplete and compile-time checks. * Stress that understanding the response object makes everything else easier. Once you know the shape, rendering is straightforward. ## Screen: What to Show Timestamp Screen content 0:00-2:00 VS Code with empty file. Type the npm install command, then the SDK import and Contentstack.stack() call. Terminal split showing install output. 2:00-3:30 Contentstack dashboard: Settings > Stack (show API key), Settings > Tokens > Delivery Tokens (show token + environment scope), Settings > Stack Information (show region). 3:30-5:00 Back to VS Code. Complete the stack initialization with env vars. Add a simple contentType("product").entry().query().find() call. Run it. Show console output with entry array. 5:00-7:00 Live-code .entry("blt\_matrix\_link\_001").fetch() for single entry. Then .equalTo("url", "/products/digital-dawn/matrix-link-bracelet") for URL-based fetch. Run both, compare output shapes. 7:00-9:00 Build query chains live: .where("price", QueryOperation.IS\_GREATER\_THAN, 200), then add .orderByAscending("price"), then .limit(5).skip(0). Run after each addition so viewers see the query narrowing. 9:00-11:00 Show a product response with unresolved reference stubs. Add .includeReference("product\_line").includeReference("category"). Run again. Highlight the before/after difference in the console -- stubs vs full objects. 11:00-12:30 Show nested include: .includeReference("product\_line.products"). Run it. Show the expanded payload. Briefly open browser DevTools Network tab to show response size difference. 12:30-14:00 Add .locale("fr-fr") to the query. Run it. Show translated fields. Remove .includeFallback() and show blank fields. Add it back. Show fallback content appearing. 14:00-16:00 Switch to a React component file. Map the response to props: product.title, product.price, product.product\_line\[0\]?.title. Show null-safe access patterns. 16:00-18:00 Add TypeScript generics: query.find(). Show autocomplete kicking in. Show a type definition file matching the content type schema. 18:00-end Browser showing rendered Veda product page with data flowing from Contentstack. Zoom into the product card showing title, price, product line name, category. ## Veda Scenario Thread Veda: The Revival Collection (jewelry e-commerce) runs through this entire video as the practical context. * **Opening:** "We have a Veda jewelry catalog with products, product lines, and categories. Let us connect to it." Initialize the SDK with Veda stack credentials. * **First queries:** Fetch all Veda products. Then filter to products over $200 -- show items like the Matrix Link Bracelet ($295) appearing in results. * **Single entry:** Fetch the Matrix Link Bracelet by UID (blt\_matrix\_link\_001) and by URL (/products/digital-dawn/matrix-link-bracelet). Show both paths to the same entry. * **References:** Show the Matrix Link Bracelet with unresolved product\_line and category stubs. "Right now we know this product belongs to _something_, but we do not know what." Add includeReference() calls. "Now we see Digital Dawn and Bracelets." * **Nested references:** Include product\_line.products to show other products in the Digital Dawn line (Pixel Stud Earrings, etc.). Talk about when this depth is worth the payload cost. * **Localization:** Switch the query to fr-fr. Show the Matrix Link Bracelet with French title ("Bracelet Maillon Matrice") where translated, English fallback where not. Show the gap without includeFallback(). * **Rendering:** Build a simple Veda product card component. Map product.title, product.price, product.product\_line\[0\].title, product.category\[0\].title to the card layout. Show it rendering in the browser. * **Closing:** "This is how Veda goes from CMS entries to a rendered product page. Every query pattern we covered -- filtering, pagination, references, localization -- is something you will use building pages like this." ## Transitions 1. **Intro to SDK initialization:** "Before you can render anything, you need a connection to your stack. Let us set one up." 2. **SDK init to stack client setup:** "The stack instance is created. Now let us look at what configuration options matter and where to find each credential." 3. **Stack client to fetching entries:** "Configuration is done. Time to fetch actual content." 4. **Fetching entries to query chaining:** "Fetching everything is a start, but real apps need filters, sorting, and pagination." 5. **Query chaining to live coding:** "Enough theory. Let us write these queries against real Veda data and see what comes back." 6. **Live coding to references and includes:** "Our queries return products, but the product line and category fields are just UID stubs. Let us fix that." 7. **References to localization:** "References are resolved. Now what happens when your site serves content in multiple languages?" 8. **Localization to rendering:** "We can fetch content in any locale with fallbacks. The last step is mapping this data to components." 9. **Closing to Video 7:** "You now know how to fetch, filter, resolve, and render content from Contentstack. In the next video, we tackle Live Preview -- seeing content changes in real time before they are published." ## Common Mistakes to Call Out * **Wrong region, silent failure:** Initializing with Region.US when the stack is in EU. The SDK does not tell you the region is wrong. You get empty results or a 401. Always verify in Settings > Stack Information. * **Environment/token mismatch:** The delivery token is scoped to one environment. Using a staging token with environment: "production" fails silently or returns auth errors. * **Empty credential strings:** The SDK accepts empty strings at init time without throwing. The first query fails with a cryptic 401 or 412. Validate credentials before the first query. * **Using content type UID instead of field UID in** **includeReference()****:** include\[\]=categories when the field UID is category returns 200 but references stay as stubs. The parameter is the _field UID_ on the parent, not the target content type UID. * **Forgetting** **includeFallback()** **on partially localized stacks:** Without it, untranslated fields return empty. Visitors see blank sections instead of parent-locale content. * **Over-including nested references:** Including product\_line.products.category (three levels deep) balloons the response payload. Only include what the current view actually renders. * **Assuming all referenced entries exist in all locales:** If categories are only in English and you request ja-jp without fallback, categories come back empty or missing entirely. * **Not handling null fields in rendering:** Partial localization and optional fields mean any field can be null. Always use null-safe access (product.product\_line\[0\]?.title) or default values. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 6 — Fetching and Rendering Content with the SDK** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 08 — Video Production Plan : Video 7 — Performance, Images, Environments, and CLI Migrations #### Lesson text # Video 7 — Performance, Images, Environments, and CLI Migrations Attribute Details Course 3 (APIs and Developer Tooling), Module 3.2 (lessons 3-4) + Module 3.3 Covers Lessons 3.2.3, 3.2.4, 3.3.1, 3.3.2, 3.3.3 Priority Core Length 20-28 min Format Screencast (terminal + Contentstack UI + code editor) Status Not started ## Why This Video Matters This turns Contentstack from a simple content source into an operationally mature implementation. A working integration is not the same thing as a production-ready integration. ## Outline 1. Image Delivery API: URL-based transformations (resize, crop, format conversion, quality) 2. Show image transformation parameters and their impact on page performance 3. Responsive image strategies 4. Caching strategies: CDN behavior, cache invalidation on publish, stale-while-revalidate patterns 5. Frontend rendering strategies: SSG (build-time), SSR (request-time), ISR (incremental), CSR (client-side) — when each makes sense 6. Environments explained: development, staging, production — each with its own publish queue and delivery token 7. Content promotion: publishing to dev first, then staging, then production 8. Aligning CMS environments with CI/CD pipelines 9. Contentstack CLI (csdx): installation, authentication, key commands 10. Live demo: export a stack, import into another, run a content type migration 11. Migration scripts: programmatically creating and modifying content types 12. When to use CLI vs UI vs Management API ## Key Lines "A working integration is not the same thing as a production-ready integration." "Environment strategy is where content delivery and deployment reality meet." "The CLI is where repeatability starts to replace manual effort." ## Detailed Talking Points ### 1\. Image Delivery API: URL-based transformations * Contentstack serves every uploaded asset through its Image Delivery CDN — the URL you get back from the Delivery API is already on the CDN. * Transformations are query parameters appended to the URL: ?width=400, ?height=300, ?format=webp, ?quality=80, ?crop=400,400,x100,y50, ?fit=crop. * No build step, no image processing pipeline, no Lambda function — the CDN handles transformation and caching at the edge. * The ?auto=webp parameter is the easiest win: it inspects the browser's Accept header and serves WebP when supported, falling back automatically. Typical savings: 25-35% payload reduction. * Region matters for the host: NA uses images.contentstack.io, EU uses eu-images.contentstack.com, Azure variants exist too. * Combined parameters in one URL: ?width=800&height=600&fit=crop&format=webp&quality=80 — one request, one cached result. ### 2\. Image transformation parameters and performance impact * Show a before/after: original 4000px product image vs. ?width=800&auto=webp&quality=80. Compare file sizes in the Network tab. * Quality between 70-85 is the sweet spot for product photography. Below 60, compression artifacts become visible. * The fit parameter controls behavior when both width and height are set: bounds scales to fit within dimensions, crop fills exact dimensions and trims overflow. * trim=20,20,20,20 removes uniform whitespace — useful for product catalog images with inconsistent borders. * The key principle: always match ?width= to the rendered size. A 4000px image displayed at 800px wastes bandwidth and tanks your LCP score. ### 3\. Responsive image strategies * Use srcset to give the browser multiple width options: 400w, 800w, 1200w, 1600w — all generated by varying the ?width= parameter on the same base URL. * Pair srcset with sizes to tell the browser how wide the image renders at each breakpoint: (max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw. * Build a buildImageUrl() and buildSrcSet() utility function rather than constructing URLs manually — avoids string concatenation bugs and enforces consistent quality/format settings. * Art direction with different crops: use ?crop= or ?fit=crop with different aspect ratios for mobile vs. desktop hero images. * Always set explicit width and height attributes on elements to prevent CLS (Cumulative Layout Shift). * Use loading="lazy" for below-fold images, omit it (or use loading="eager") for above-fold hero images. * Preload the LCP image with . ### 4\. Caching strategies * Contentstack's CDN invalidates on publish — when an editor publishes or unpublishes, stale cache entries are evicted globally within seconds. * Between publishes, identical API calls resolve at the CDN edge without hitting origin servers. * Draft saves do not affect the delivery cache. Only the publish action triggers invalidation. * Contentstack sends Cache-Control: public, max-age=0, must-revalidate — the CDN is the source of truth, not the browser cache. * If you add your own caching layer (Redis, edge cache, in-memory), you must add webhook-driven invalidation. Contentstack only purges its own CDN, not yours. * The stale-while-revalidate pattern: serve cached content immediately, fetch fresh content in the background. Ideal for content that updates periodically but where a few seconds of staleness is acceptable. ### 5\. Frontend rendering strategies * SSG (Static Site Generation): pages built at build time, served from static CDN. Fastest possible load. Content only updates on rebuild. Best for: stable pages, reference content, documentation. * SSR (Server-Side Rendering): page generated on every request. Always fresh. Adds latency (API call + render). Best for: personalized content, search results, breaking news. * ISR (Incremental Static Regeneration): hybrid — static pages that regenerate after a time interval or on-demand. Combine revalidate = 60 with webhook-triggered revalidation for best of both worlds. * CSR (Client-Side Rendering): SPA pattern, content fetched in the browser after initial load. No SEO benefit from CMS content. Best for: authenticated dashboards, interactive tools. * For Veda: homepage gets ISR with 30s revalidation, product pages get ISR with 60s, category pages get SSG with webhook-triggered rebuilds, search results get SSR. * Webhook-triggered rebuilds close the loop: editor publishes → Contentstack fires webhook → hosting platform triggers rebuild → new static site deploys in 30-120 seconds. ### 6\. Environments explained * An environment in Contentstack is a deployment target, not a code branch. This trips up developers from git-centric workflows. * Typical setup: development (dev integration testing), staging (QA and stakeholder review), production (live customer-facing). * Each environment gets its own delivery token. Your production frontend uses a production-scoped token. Staging uses a different token. * Token isolation limits blast radius — if a staging token leaks, production content is unaffected. * Each environment has independent published content state. Publishing to staging does not make content available in production. * Environments have a Base URL (the frontend that consumes content) and an optional Preview URL for Live Preview. ### 7\. Content promotion flow * Promotion strategy mirrors application deployment: dev → staging → production. * Editor creates entry, publishes to development. Developer verifies rendering. Editor promotes to staging for QA review. Senior editor publishes to production. * Each publish action is explicit and auditable. Content does not drift between environments without intentional action. * Publish rules restrict which roles can publish where: Content Authors to dev only, Content Managers to dev and staging, Senior Editors to production. * Publish assets before the entries that reference them to avoid broken references on the target environment. * The publish queue processes requests asynchronously — clicking Publish does not guarantee instant CDN availability. Monitor the queue for large bulk operations. ### 8\. Aligning CMS environments with CI/CD pipelines * Content publishes and code deploys operate on independent timelines — this independence is a feature, not a flaw, but it creates a coordination problem. * The primary integration point: webhooks. Contentstack fires HTTP webhooks on publish events. Point them at your build hook (Vercel deploy hook, Netlify build hook, GitHub Actions dispatch). * Filter webhooks by environment and content type. Development publishes should not trigger production builds. Metadata-only content types should not trigger rebuilds. * Content-as-code: export content type schemas with the CLI, commit them to version control. Add a CI step that detects schema drift between Contentstack and your committed definitions. * Manage delivery tokens as CI/CD secrets. Each CI/CD context (preview, staging, production) injects the correct token via environment variables. * Rollback order matters: revert code first (restore the frontend that expects the old schema), then republish previous content versions. ### 9\. Contentstack CLI: installation, authentication, key commands * Install globally: npm install -g @contentstack/cli. Verify with csdx --version. * Interactive login: csdx auth:login opens browser-based OAuth. Good for local dev, not for CI/CD. * Token-based auth for automation: csdx auth:tokens:add --alias "my-stack" --stack-api-key "..." --management --token "..." --yes. * Token aliases simplify repeated operations — reference \--alias my-stack instead of passing raw keys every time. * List stored tokens: csdx auth:tokens. Remove a token: csdx auth:tokens:remove --alias "my-stack". * The CLI uses a plugin architecture. Core commands cover stack management, content export/import, and authentication. ### 10\. Live demo: export, import, and migration * Export a full stack: csdx cm:stacks:export --alias "source" --data-dir ./export-data. * Export specific modules: \--module content-types --module global-fields --module assets. * Show the exported directory structure: JSON files organized by module — content-types/product.json, entries/product/en-us/, assets/. * Import into target: csdx cm:stacks:import --alias "target" --data-dir ./export-data. * Use \--replace-existing to overwrite existing content types during import. * Always back up before importing to production: csdx cm:stacks:export --alias "prod" --data-dir ./backup/$(date +%Y%m%d). * Seed a new stack from a template: csdx cm:stacks:seed --repo "contentstack/stack-starter-app". ### 11\. Migration scripts * For changes beyond simple export/import — renaming fields, transforming data, backfilling values — use programmatic scripts with the Content Management API. * Example: backfill a description\_word\_count field across all Veda product entries. Fetch entries via CMA, calculate the value, update each entry. * Migration scripts give you full control over transformation logic, error handling, and execution order. * Wrap CLI export/import in CI/CD pipelines (GitHub Actions workflow) for automated content model sync across multiple stacks. * Use workflow\_dispatch with matrix strategy to fan out imports across brand stacks in parallel. ### 12\. When to use CLI vs UI vs Management API * UI: one-off content type changes, small-scale content edits, exploratory work. Fast feedback, no scripting needed. * CLI (csdx): repeatable operations across stacks — export/import, seeding, bulk operations. Scriptable, auditable, belongs in CI/CD. * Management API (CMA): programmatic migrations, custom tooling, data transformations, backfills. Full control, requires code. * Rule of thumb: if you are doing it once, use the UI. If you are doing it more than once, use the CLI. If you need transformation logic, use the CMA. * Treat content migrations like database migrations: plan them, test against non-production, back up before production, log everything. ## Screen: What to Show Outline Item What to Show on Screen 1\. Image Delivery API Browser with a Contentstack asset URL. Append ?width=400&format=webp&quality=80 live in the address bar. Show the image changing/resizing in real time. 2\. Transformation impact Chrome DevTools Network tab. Load a product page with original images, then with optimized URLs. Compare file sizes side by side (highlight the KB reduction). 3\. Responsive images Code editor showing a buildImageUrl() and buildSrcSet() utility function. Then the rendered HTML element with srcset in Elements panel. Use Chrome responsive mode to show different image sizes loading at different breakpoints. 4\. Caching Chrome DevTools Network tab — show a Contentstack API response with Cache-Control headers. Then show a publish action in Contentstack UI and the subsequent fresh response. Optionally show a simple stale-while-revalidate code snippet. 5\. Rendering strategies Side-by-side diagram or slide: SSG vs SSR vs ISR vs CSR with arrows showing when the API call happens (build time, request time, background, client). Show Next.js code with revalidate = 60 and a revalidation API route. 6\. Environments Contentstack dashboard: Settings > Environments. Show the three environments (development, staging, production) with their Base URLs. Then Settings > Tokens showing three delivery tokens, one per environment. 7\. Content promotion Contentstack entry editor. Click Publish, show the environment selector. Publish to development first, then show the entry in staging (not yet published), then publish to staging. Show the publish queue (Settings > Publish Queue). 8\. CI/CD alignment Code editor: show a webhook handler that filters by environment and content type. Then Contentstack dashboard: Settings > Webhooks configuration. Optionally show a GitHub Actions schema-drift-check workflow YAML. 9\. CLI installation and auth Terminal: npm install -g @contentstack/cli, csdx --version, csdx auth:tokens:add with alias. Show the token list with csdx auth:tokens. 10\. Live demo Terminal: run csdx cm:stacks:export and show the output directory. Open a JSON file in the editor. Run csdx cm:stacks:import against a target stack. Switch to Contentstack UI to verify the imported content types appear. 11\. Migration scripts Code editor: show a TypeScript migration script that uses @contentstack/management to backfill a field. Run it in the terminal with npx tsx scripts/backfill.ts. Show the updated entries in Contentstack UI. 12\. CLI vs UI vs CMA Simple three-column comparison slide or table on screen. No code needed — just a clear visual summary. ## Veda Scenario Thread Veda: The Revival Collection (jewelry e-commerce) runs through this entire video as the practical context. * **Images (items 1-3):** You are optimizing Veda product images. Start with a Matrix Link Bracelet product photo served at full resolution (4000px). Show how appending ?width=800&auto=webp&quality=80 slashes the file size. Build the buildSrcSet() utility for the product card grid — 300w, 600w, 900w breakpoints for the Pixel Stud Earrings, Circuit Collar Necklace, and Data Drop Earrings product cards. Add for the Digital Dawn hero image on the homepage. * **Caching and rendering (items 4-5):** Veda's homepage uses ISR with 30-second revalidation because campaign launches need fast propagation. Product pages use ISR with 60-second revalidation and webhook-triggered on-demand revalidation. Category pages use SSG with webhook-triggered rebuilds. Search results use SSR because query parameters vary per request. Show a webhook handler that triggers a Vercel rebuild only for product, page, and product\_line content types on the production environment. * **Environments (items 6-7):** Veda has three environments: development at dev.veda.example.com, staging at staging.veda.example.com, production at veda.example.com. Walk through publishing a new seasonal collection entry: publish to dev for developer verification, promote to staging for the merchandising team, then production for the customer-facing storefront. Show how publish rules prevent a junior content author from accidentally pushing an unreviewed product to production. * **CI/CD (item 8):** Veda's CI/CD pipeline on Vercel uses environment-specific delivery tokens injected as environment variables. A webhook fires on production publish and triggers a rebuild. The content type schemas are exported and committed to the repo, with a GitHub Actions step that detects schema drift on pull requests. * **CLI and migrations (items 9-12):** Veda is expanding from one brand stack to three brand stacks (Alpha, Beta, Gamma). Use the CLI to export the product and category content types from the Alpha stack, import them into Beta and Gamma. Then run a migration script that backfills a description\_word\_count field across all product entries in all three stacks. Wrap the workflow in a GitHub Actions pipeline with matrix strategy for parallel execution. ## Transitions 1 → 2: "Now that you see how the URL parameters work, let us look at the actual performance impact in the browser." 2 → 3: "Optimizing one image is useful — building a system that optimizes every image across your product catalog is what matters." 3 → 4: "Images are cached at the CDN edge, but what about the API responses that tell you which images to show?" 4 → 5: "Caching controls when data refreshes — rendering strategy controls when pages are built from that data." 5 → 6: "Rendering strategies tie to environments, because each environment serves different content to a different audience." 6 → 7: "Having environments is one thing — having a disciplined flow for moving content through them is another." 7 → 8: "Content promotion aligns with code deployment, and that is where CI/CD integration becomes essential." 8 → 9: "The CI/CD pipeline needs tooling to automate content operations, and that tooling is the Contentstack CLI." 9 → 10: "Let us stop talking about the CLI and start using it." 10 → 11: "Export and import handle structural replication — migration scripts handle data transformation." 11 → 12: "With three tools in your belt — CLI, UI, and Management API — you need to know when to reach for each one." 12 → Video 8: "You now have the operational foundation: optimized images, caching strategy, environment discipline, and CLI automation. In the next video, we bring it all together with Contentstack Launch and a full deployment walkthrough." ## Common Mistakes to Call Out 1. **Serving full-resolution images at display size.** A 4000px image displayed at 800px wastes bandwidth and destroys your LCP score. Always match ?width= to the rendered size. 2. **Skipping** **auto=webp****.** A single query parameter reduces payload by 25-35% with zero effort. There is no reason not to use it. 3. **Missing** **width** **and** **height** **attributes on** **** **elements.** Without them, the browser cannot reserve space before the image loads, causing layout shifts that tank your CLS score. 4. **Adding a caching layer without webhook-driven invalidation.** Contentstack only invalidates its own CDN. If you add Redis, edge cache, or in-memory cache without a purge mechanism, editors publish content that never appears on the site. 5. **Using SSR for everything.** SSR guarantees freshness but wastes resources on pages that rarely change. Product pages, category pages, and documentation should use SSG or ISR. 6. **Confusing environments with branches.** Environments are deployment targets (dev, staging, production). Branches are for parallel content development. Creating an environment called feature-new-checkout is misusing the system. 7. **Publishing directly to production without staging verification.** Skipping staging saves a few minutes and costs hours when broken content, missing references, or layout issues reach customers. 8. **Sharing delivery tokens across environments.** Using the production token in your staging frontend defeats environment isolation. Each frontend deployment must use the token scoped to its corresponding environment. 9. **Publishing entries before their referenced assets.** A product entry referencing an unpublished hero image produces a broken storefront page. Publish assets first. 10. **Running** **\--replace-existing** **imports on production without a backup.** Always export the current state before migrating production: csdx cm:stacks:export --alias "prod" --data-dir ./backup/$(date +%Y%m%d). 11. **N+1 query patterns in template loops.** A loop over 20 products that fetches product line data per iteration makes 21 API calls instead of 1. Use includeReference() to resolve references in the original query. 12. **Hardcoding stack credentials in migration scripts.** Use environment variables or the CLI's token alias system. Never commit API keys or management tokens to version control. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 7 — Performance, Images, Environments, and CLI Migrations** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 09 — Video Production Plan : Video 8 — Live Preview Architecture and Preview Routing #### Lesson text # Video 8 — Live Preview Architecture and Preview Routing Attribute Details Course 4 (Preview, Visual Builder, and Releases), Module 4.1 (lessons 1-3) Covers Lessons 4.1.1, 4.1.2, 4.1.3 Priority Critical Length 18-25 min Format Screencast (code editor + Contentstack UI side-by-side) Status Not started ## Why This Video Matters Preview is one of the places where a visual explanation helps much more than text alone. Headless architectures do not give you preview for free — it requires deliberate implementation. ## Outline 1. Why Live Preview matters: editors need to see changes before publishing; without it, they fly blind 2. The two-delivery-plane mental model: preview token vs delivery token 3. Requirements: what your frontend needs to support (SDK initialization with live preview config, preview token, host URL) 4. Draft vs published routing: how to serve draft content in preview mode and published content in production 5. Show the configuration in Contentstack settings and the corresponding frontend code 6. SSR preview pattern: server fetches draft content on each request 7. CSR preview pattern: client-side SDK listens for changes and re-renders in real time 8. onEntryChange, edit tags, and preview transport 9. Walk through a working Live Preview implementation step by step 10. Common failure modes: CORS issues, wrong environment tokens, caching interfering with draft content ## Key Lines "Headless architectures do not give you preview for free." "Preview is a product capability, not a side feature." "If preview behavior is inconsistent, editorial trust erodes quickly." ## Detailed Talking Points ### 1\. Why Live Preview matters * Headless CMS architectures do not provide preview out of the box. Preview is an architecture concern, not a UI toggle. * Without preview, editors "fly blind" -- they publish content hoping it looks right, or they ask developers to check for them. Both are slow and error-prone. * Preview is a correctness system. When an editor asks "is this page ready?", they are asking a systems question: can I trust what I see before I hit publish? * Unreliable preview leads to two failure modes: teams publish too cautiously (slow velocity) or too optimistically (broken pages in production). * Frame preview as a product capability, not a nice-to-have. Treat preview correctness as a release criterion. ### 2\. The two-delivery-plane mental model * Split content delivery into two planes: the published plane (optimized for live user traffic, CDN-cached, Delivery Token) and the preview plane (optimized for draft validation, no caching, Preview Token). * If you treat preview as "published plus a flag," you get inconsistent results. Preview has different host routing, request context, and caching expectations. * Published traffic goes to cdn.contentstack.io (or your region's CDA host). Preview traffic goes to rest-preview.contentstack.com (or your region's preview host). * Both tokens are scoped to an environment. The difference: the Delivery Token only returns published entries. The Preview Token returns the latest saved version of every entry, regardless of publish state. * The Preview Token does not bypass environments -- it bypasses the publish gate. An entry does not need to be published for the Preview Token to return it. ### 3\. Requirements: SDK initialization and preview config * Three things your frontend needs: the Live Preview SDK (@contentstack/live-preview-utils), a Preview Token, and the correct preview host URL for your region. * Initialize the Delivery SDK with live\_preview config: enable: true, preview\_token, and host pointing to your region's preview endpoint. * Initialize ContentstackLivePreview.init() separately with ssr: true or ssr: false (matching your rendering model), mode: "builder", stackSdk, stackDetails, and clientUrlParams.host pointing to your region's Contentstack app URL. * The clientUrlParams.host must match the Contentstack web app for your region (e.g., eu-app.contentstack.com for AWS EU). Getting this wrong causes silent failures. * Use @timbenniks/contentstack-endpoints to resolve correct base URLs for any region string -- avoids hardcoding the wrong host. * The editButton config with exclude: \["outsideLivePreviewPortal"\] ensures the floating edit button only appears inside the Contentstack preview iframe. ### 4\. Draft vs published routing * Two hosting approaches: separate preview host (recommended) or single host with mode switching. * Separate host: www.example.com runs with Delivery Token, preview.example.com runs with Preview Token. Same codebase, different env vars. Complete isolation. * Single host with mode switching: detect preview mode via URL param (?live\_preview), cookie, or header. Cheaper infrastructure but riskier -- a bug in mode-switching logic could expose draft content to production visitors. * Preview URL structure must mirror production URL structure exactly. If production serves /blog/q3-report, preview must serve /blog/q3-report at the same path. Otherwise editors land on 404s. * In Contentstack, configure the preview base URL under Settings > Live Preview. The CMS constructs preview URLs by combining this base URL with the entry's URL path. ### 5\. Configuration walkthrough (Contentstack settings + frontend code) * Show Settings > Tokens: where to create Preview Token and Delivery Token. * Show Settings > Live Preview: where to set the preview URL base and enable Live Preview for the stack. * Show the .env.production vs .env.preview files side by side: same API key, same environment, different tokens and PREVIEW=true/false flag. * Show the SDK initialization code: how the live\_preview block conditionally enables preview based on the env var. * Emphasize: both deployments share the same Git repository. The only difference is environment variables injected at build/deploy time. ### 6\. SSR preview pattern * Server fetches draft content on each request using the Preview Token. The server renders HTML and sends it to the browser. * The Live Preview SDK initializes on the client with ssr: true. When the editor modifies content, the SDK triggers a page refresh via router.refresh() (Next.js App Router) or window.location.reload(). * router.refresh() is strongly preferred: it re-runs server components without a full page reload, preserving scroll position and client state. * SSR preview is structurally simpler -- no client-side data management. The trade-off is latency: each update requires a server round-trip (typically 200-500ms). * Critical: caching must be explicitly disabled for preview requests. In Next.js App Router, fetch() is cached by default. Set cache: "no-store" or next: { revalidate: 0 } for preview fetches, or editors will see stale content. ### 7\. CSR preview pattern * The browser fetches content directly from Contentstack and renders it in the DOM. Updates are instant and data-driven. * Initialize the SDK with ssr: false. Register ContentstackLivePreview.onEntryChange(callback) -- the callback fires every time the editor modifies a field. * When onEntryChange fires, the SDK has already intercepted the Delivery SDK instance. The re-fetch returns real-time draft data from the postMessage payload -- no network call. The component re-renders instantly. * CSR preview gives the best editor experience: sub-second updates, no page flicker, no scroll position loss. * For hybrid pages (SSR page shell + CSR interactive components), keep SSR-fetched fields on the server path and CSR-fetched fields on the client path. Never mix data sources for the same field -- it creates synchronization bugs where server HTML and client updates disagree. ### 8\. onEntryChange, edit tags, and preview transport * onEntryChange is the primary hook for responding to Live Preview updates. Its behavior depends on the ssr flag. * With ssr: false: callback gets updated data instantly from the postMessage payload. No network round-trip. * With ssr: true: callback triggers a page refresh so the server re-fetches with the updated live\_preview hash. * Edit tags are data-cslp attributes on DOM elements. Format: {content\_type\_uid}.{entry\_uid}.{locale}.{field\_path}. They map rendered content to CMS fields for field-level highlighting and in-place editing. * The postMessage bridge handles all communication between the Contentstack entry editor (parent window) and your app (iframe): handshake, entry changes, hash updates, and navigation events. * You never implement postMessage handling yourself -- the SDK manages it. But knowing it exists explains why Live Preview requires an iframe context and why CORS can block it. ### 9\. Walk through a working implementation step by step * Start from zero: create tokens, configure Live Preview settings, set up env vars, initialize SDKs. * Show the full request flow: editor opens Live Preview, CMS loads preview URL in iframe, SDK detects iframe context, SDK intercepts API calls and redirects to preview host with Preview Token. * Demonstrate a content change: editor types a new headline, postMessage fires, onEntryChange triggers, page updates (instant for CSR, server round-trip for SSR). * Show the live\_preview hash in action: without the hash, preview API returns last saved draft. With the hash, it returns real-time editing state including unsaved changes. * Show edit tags lighting up on hover: the data-cslp attributes enable field-level highlighting so editors can see exactly which DOM element maps to which CMS field. ### 10\. Common failure modes * CORS issues: the Contentstack app and your preview deployment are on different origins. If your server blocks cross-origin iframe embedding or postMessage, Live Preview silently fails. Check X-Frame-Options and CSP headers. * Wrong environment tokens: using a Delivery Token in the preview deployment means editors only see published content. This often goes unnoticed during setup because testing happens with already-published entries. The bug surfaces when an editor creates a brand-new entry and preview shows a 404. * Caching interfering with draft content: CDN caching preview responses, browser caching from a previous production visit, or Next.js fetch cache serving stale data. All three produce the same symptom: editor saves changes, refreshes, sees old content. * Missing or wrong preview host configuration: hardcoding the wrong region's preview host, or forgetting to set clientUrlParams.host to the correct Contentstack app URL. Both cause silent failures. * SSR state leakage: storing preview state globally in a long-lived server process. One editor's draft context leaks into another editor's request, producing non-deterministic preview results. * Wrong ssr flag: initializing with ssr: false in an SSR app causes the SDK to intercept client-side calls that never fetch data. Result: confusing flicker where server HTML shows old content, client briefly shows new content, then hydration conflicts. ## Screen: What to Show Outline item What to show on screen Opening (outline items 1-2) Contentstack entry editor: Show an entry with unpublished draft changes. Point out the "Save" vs "Publish" distinction. Click Live Preview to open the preview panel -- show how it loads the preview URL in an iframe. Whiteboard or slide: Two-plane diagram. Left side: "Published Plane" with Delivery Token arrow to  cdn.contentstack.io . Right side: "Preview Plane" with Preview Token arrow to  rest-preview.contentstack.com . Keep this visible as a reference throughout.  SDK setup (outline items 3, 5) Contentstack dashboard: Navigate to Settings > Tokens. Show where Preview Token and Delivery Token are created. Highlight that both are scoped to an environment. Contentstack dashboard: Navigate to Settings > Live Preview. Show the Preview URL field and the enable toggle. Code editor (split view): Show  .env.production  and  .env.preview  side by side. Highlight the differences:  PREVIEW\_TOKEN  present only in preview,  PREVIEW=true  only in preview. Code editor: Show the SDK initialization code. Highlight  live\_preview.enable ,  live\_preview.preview\_token ,  live\_preview.host . Then show  ContentstackLivePreview.init()  with  ssr ,  mode ,  stackSdk ,  clientUrlParams.host .  Routing (outline item 4) Browser: Open  www.example.com/blog/post  and  preview.example.com/blog/post  in side-by-side tabs. Show that the published version shows published content, the preview version shows draft content including unpublished changes. Code editor: Show the middleware or env-var logic that switches between Delivery Token and Preview Token based on mode.  SSR pattern (outline item 6) Code editor: Show the Next.js App Router server component fetching content with  draftMode() . Show the  cache: "no-store"  setting on the fetch call. Code editor: Show the client component with  ContentstackLivePreview.init({ ssr: true })  and  onEntryChange(() => router.refresh()) . Live demo: Edit a field in the Contentstack entry editor and show the SSR preview update in real time. Point out the slight delay from the server round-trip.  CSR pattern (outline item 7) Code editor: Show the React hook with  onEntryChange(fetchEntry)  and  ssr: false . Live demo: Edit a field and show the instant client-side re-render. Compare the speed to the SSR pattern.  Edit tags and transport (outline item 8) Code editor: Show  data-cslp  attributes on DOM elements. Explain the format:  content\_type.entry\_uid.locale.field\_path . Browser DevTools: Inspect an element in the preview iframe and show the  data-cslp  attribute. Hover over content in the preview panel and show the field-level highlighting.  Working implementation walkthrough (outline item 9) Full-screen code editor + preview panel: Walk through the complete flow from token creation to a working Live Preview. Show the live\_preview hash in the network tab -- the SDK sends it with each request. Failure modes (outline item 10) Browser DevTools (Console tab): Show a CORS error when  X-Frame-Options  blocks the iframe. Show how to fix it. Browser DevTools (Network tab): Show a preview request returning published content because the wrong token was used. Show the  access\_token  header vs  preview\_token  header. Browser DevTools (Network tab): Show a cached response with  Cache-Control: public  on a preview request. Show the fix:  no-store  headers. ## Veda Scenario Thread Veda is the fictional luxury jewelry brand used throughout this certification course. Use it as the running example in this video. * **Opening:** Veda's content team just hired a new marketing editor. She needs to preview a new product page for the "Matrix Link Bracelet" before publishing. Without Live Preview, she would have to publish to staging, check the page, then unpublish if something is wrong. That is a broken workflow. * **Two-plane model:** Veda runs two deployments: www.veda.com (production, Delivery Token, CDN-cached) and preview.veda.com (preview, Preview Token, no caching). Same Next.js codebase, different env vars. * **SDK initialization:** Show the Veda project's lib/contentstack.ts file. Walk through how the region is set to eu (Veda is a European brand), and how getContentstackEndpoints("eu", true) resolves the correct preview and app hosts for AWS EU. * **Draft vs published routing:** The editor opens the "Matrix Link Bracelet" product entry in Contentstack. She clicks Live Preview. Contentstack loads preview.veda.com/products/matrix-link-bracelet in the iframe. The preview deployment fetches draft content using the Preview Token. * **SSR pattern:** Veda's product pages are server-rendered for SEO (title, description, structured data). The server fetches draft content on each preview request. router.refresh() handles updates. * **CSR pattern:** Veda's "Related Products" carousel is client-rendered. It uses onEntryChange to re-render in place when the editor changes related product references. * **Edit tags:** The editor hovers over the product title on the preview page. The data-cslp="product.blt\_matrix\_link\_001.en-us.title" attribute lights up, showing her exactly which field maps to that heading. She clicks and edits in place. * **Failure mode demo:** Show what happens if Veda's preview deployment accidentally uses the Delivery Token -- the new "Matrix Link Bracelet" entry (never published) returns a 404 in preview. Fix it by swapping to the Preview Token. ## Transitions 1. **Item 1 to 2:** "So if preview is not free, how does Contentstack actually separate draft content from published content? It comes down to two delivery planes." 2. **Item 2 to 3:** "Knowing the model is one thing -- now let us look at what your frontend code needs to support it." 3. **Item 3 to 4:** "The SDK is initialized, but how does your app decide when to use the Preview Token versus the Delivery Token? That is routing." 4. **Item 4 to 5:** "Let me show you exactly where this is configured -- both in Contentstack's dashboard and in the frontend code." 5. **Item 5 to 6:** "Configuration is done. Now let us see how preview actually works at runtime, starting with server-side rendering." 6. **Item 6 to 7:** "SSR preview works, but it has a round-trip delay. Client-side rendering gives you instant updates -- here is how." 7. **Item 7 to 8:** "Both patterns rely on the same underlying mechanisms: onEntryChange, edit tags, and postMessage transport. Let us look at those." 8. **Item 8 to 9:** "Now that you understand all the pieces, let us put them together in a complete working implementation." 9. **Item 9 to 10:** "Before we wrap, let me show you the most common ways Live Preview breaks -- so you can avoid them." 10. **Closing to Video 9:** "Live Preview gives editors visibility into draft content. But seeing content is only half the story -- in the next video, we will look at Visual Builder, which lets editors actually edit content in place, directly on the page." ## Common Mistakes to Call Out * **Using the Delivery Token in the preview deployment.** Editors only see already-published content. New entries and draft changes are invisible. The bug hides during setup because developers test with already-published entries. It surfaces when an editor creates a new entry and gets a 404. * **Applying production cache rules to the preview host.** CDN, browser, and framework fetch caches all need explicit no-cache configuration for preview. One missed layer means editors see stale content and lose trust in the entire preview system. * **Mismatched URL paths between preview and production.** If preview uses a different routing scheme (e.g., /preview/blog/slug instead of /blog/slug), Contentstack cannot construct the correct preview URL. Editors land on 404 pages. * **Setting** **ssr: false** **in an SSR application.** The SDK tries to intercept client-side SDK calls that never actually fetch data. Result: server HTML shows old content, client briefly flashes new content, then hydration conflicts cause unpredictable behavior. * **Forgetting to disable fetch caching in SSR preview mode.** In Next.js App Router, fetch() is cached by default. Without cache: "no-store" on preview requests, the server returns stale published content even with a Preview Token. * **Using** **window.location.reload()** **instead of** **router.refresh()** **in Next.js.** Full page reload discards client state, resets scroll position, and forces a complete HTML re-parse. router.refresh() re-runs server components smoothly. * **Storing preview state globally in a long-lived server process.** One editor's draft context leaks into another editor's request, producing non-deterministic preview. Preview state must be request-scoped. * **Missing** **clientUrlParams.host** **configuration.** The SDK needs the Contentstack app URL for your region to establish the postMessage bridge. Without it, Live Preview silently fails to communicate with the entry editor. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 8 — Live Preview Architecture and Preview Routing** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 10 — Video Production Plan : Video 9 — Visual Builder, Releases, and Future-State Preview #### Lesson text # Video 9 — Visual Builder, Releases, and Future-State Preview Attribute Details Course 4 (Preview, Visual Builder, and Releases), Module 4.1 (lessons 4-5) + Module 4.2 Covers Lessons 4.1.4, 4.1.5, 4.2.1, 4.2.2, 4.2.3 Priority Critical Length 20-30 min Format Screencast (code editor + Visual Builder in action) Status Not started ## Why This Video Matters This combines one of the most visual platform features with one of the most operationally important publishing topics. Visual Builder is the showstopper demo of the entire certification. ## Outline 1. What Visual Builder adds on top of Live Preview: click-to-edit, drag-and-drop, in-context component management 2. Architecture: how Visual Builder communicates between the Contentstack UI and your frontend 3. data-cslp and editable tagging 4. Implementation walkthrough: adding Visual Builder SDK, annotating components, registering editable regions 5. Show the editor experience: clicking on a component, editing inline, seeing changes live 6. Visual Builder with GraphQL: how to set up when your frontend uses GraphQL instead of REST 7. Localization in Visual Builder: switching locales, seeing locale-specific content render 8. Releases: bundle multiple entries and assets into a single coordinated publish action 9. Veda use case: new collection launch — product entries, landing page, navigation, assets all go live together 10. Scheduling: set a release to publish at a future date/time 11. Version comparison, rollback, and previewing future states ## Key Lines "Visual Builder only works well when the frontend is intentionally prepared for it." "Visual Builder turns your frontend into an editor's canvas. That is the promise of headless done right." "Previewing what will happen later is often more valuable than previewing what exists now." ## Detailed Talking Points ### 1\. What Visual Builder adds on top of Live Preview * Live Preview shows your frontend with draft content. Visual Builder goes further: it turns that frontend into an editable surface. * Click-to-edit: editors click directly on rendered content (a headline, an image, a CTA) and edit in place. No switching between the entry form and a preview panel. * Drag-and-drop: reorder modular block components visually, and Visual Builder reflects the new order instantly. * In-context component management: add, remove, or reconfigure components without leaving the rendered page view. * Visual Builder renders your actual production frontend inside the Contentstack UI via an iframe. Editors see exactly what visitors will see. * Key dependency: if Live Preview is not working, Visual Builder will not work either. It extends Live Preview, it does not replace it. ### 2\. Architecture: how Visual Builder communicates between the Contentstack UI and your frontend * Contentstack loads your frontend in an iframe inside the entry editor. * Visual Builder scans the iframe DOM for data-cslp attributes and creates clickable overlay regions around each tagged element. * When the editor clicks a tagged region, Visual Builder reads the data-cslp value to identify the field and opens an inline editing panel. * Communication happens over the postMessage API between the parent Contentstack window and your iframe. * The Live Preview SDK receives updated data via postMessage and re-renders the element, giving immediate visual feedback. * Changes are saved to the entry's draft state in Contentstack automatically. * MutationObserver watches for DOM changes to keep overlays positioned correctly. ### 3\. data-cslp and editable tagging * The data-cslp attribute is the contract between your frontend and Visual Builder. Without it, nothing is editable. * Format: content\_type\_uid.entry\_uid.locale.field\_path -- four parts, dot-separated. * Each part serves a purpose: content type identifies the schema, entry UID identifies the specific entry, locale identifies the language, and field path maps to the exact field. * For nested fields (groups), use dot notation: seo.meta\_title, not seo\_meta\_title. * For modular blocks, include the array index and block type: components.0.hero.title, not components.0.title. * For reference fields, decide whether to tag the reference field itself (lets editor change which entry is referenced) or the referenced entry's fields (lets editor edit the referenced content). * Incorrect paths cause silent failures: the element renders but no overlay appears, no error in the UI. * Use addEditableTags() from @contentstack/delivery-sdk to auto-generate tag values instead of hand-coding them. It attaches $ properties to each field. ### 4\. Implementation walkthrough * Step 1: Verify Live Preview works first. Check your preview deployment fetches draft content, the SDK is initialized with correct region-specific hosts, and onEntryChange callbacks fire. * Step 2: Add data-cslp attributes to all rendered content. Use addEditableTags() where possible. Pay special attention to modular blocks (include array index), group fields (dot notation), reference fields (choose the right target), and image/file fields. * Step 3: Configure Visual Builder in Contentstack stack settings under Settings > Live Preview. Enable Visual Builder, set the preview URL, and configure content type URL mapping. * Step 4: Conditionally load the Live Preview SDK. Use @contentstack/live-preview-utils, set mode: "builder", configure clientUrlParams.host to the correct application host, and set editButton.exclude: \["outsideLivePreviewPortal"\]. * Step 5: Test in the Contentstack entry editor. Switch to Visual Builder view and verify hoverable highlights, click-to-edit, and real-time updates. ### 5\. Show the editor experience * Open an entry in Contentstack and switch to Visual Builder view. * Hover over elements: highlight regions appear around every tagged element. * Click on a text field: an inline text input appears. Type changes and watch them render immediately. * Click on an image field: a file picker opens. Select a new image and it swaps in the rendered page. * Click on a rich text field: the JSON RTE editor opens inline. * Demonstrate editing a modular block component, then reordering blocks via the entry form and watching Visual Builder reflect the change. * Show that the edit button only appears inside the Contentstack portal, not when accessing the preview URL directly. ### 6\. Visual Builder with GraphQL * GraphQL uses a different preview endpoint (graphql-preview.contentstack.com pattern) and requires the Preview Token instead of Delivery Token. * The live\_preview hash must be passed as a header on each GraphQL request during a live editing session. Without it, there is a delay between keystrokes and preview updates. * data-cslp values always reference the content type schema field UID, not GraphQL aliases. If your query aliases heroTitle: title, the data-cslp must still use title. * When using GraphQL without the Contentstack JS SDK, you do not pass stackSdk to ContentstackLivePreview.init(). Instead, you manage data flow manually through onEntryChange callbacks. * For SSR with GraphQL, trigger router.refresh() in the onEntryChange callback so the server re-runs the query with the updated hash. ### 7\. Localization in Visual Builder * When an editor switches locale in the Contentstack entry editor, a postMessage is sent to the preview iframe with the new locale. * The Live Preview SDK detects the locale change and can trigger navigation to the locale-specific URL or a content refresh. * The locale in data-cslp must be dynamic and match the content being rendered. Hardcoding en-us breaks Visual Builder for every other locale. * Use ContentstackLivePreview.getLocale() in your onEntryChange handler to get the current locale and navigate accordingly. * Locale fallback behavior: if an entry is not localized for ja-jp, the preview shows English fallback content. This is correct behavior but can confuse editors. Consider adding a visual fallback indicator. ### 8\. Releases: coordinated publishing * A Release is a named collection of entries and assets that publish or unpublish together atomically. * Each item carries a publish or unpublish action, so a single Release can swap old content for new content in one operation. * Without Releases, coordinating multi-entry campaigns means publishing items one by one and hoping the timing holds. A hero banner goes live before the landing page it links to. A nav item points to a page that does not exist yet. * Three ways to add items: from the entry editor (Add to Release), from bulk actions in the entry list, or from the Release detail screen. * Releases target specific environments and locales. Most teams still promote progressively: staging first, then production. ### 9\. Veda use case: new collection launch * Veda is launching the Holiday Collection. The campaign touches 12 entries across 4 content types: homepage hero, 8 Digital Dawn products, a product line update, a navigation header change, and an old campaign page to unpublish. * Without Releases, an editor manually publishes each entry and remembers to unpublish the old banner. The margin for error is significant. * With a Release named "Holiday Collection 2025": editors prepare entries over weeks, adding each to the Release as it reaches approval. The Release manager reviews the complete list. Schedule for November 28 at midnight. All 12 entries deploy atomically. * The customer experience is seamless: one moment the site shows the previous campaign, the next it shows the Holiday Collection. No intermediate state. * Call out the Release API: Releases can be created and managed programmatically, enabling CI/CD integration and automated campaign management. ### 10\. Scheduling: set a release to publish at a future date/time * Open the Release, click Schedule Release, select environment, set date and time, choose locale, confirm. * Once scheduled, the Release enters a locked state. You cannot add or remove items without first unscheduling. * This lock prevents last-minute unreviewed changes from slipping into a coordinated deployment. * Scheduling is timezone-aware. Set the deployment time according to your business needs, not your team's timezone. * Entries must be in a publishable workflow stage before the Release fires. If an entry is stuck in "Review," it may be silently skipped or block the entire deployment. ### 11\. Version comparison, rollback, and previewing future states * Every save creates a new, immutable, complete snapshot of the entry. Not a diff, not a delta. Any version can be loaded independently. * Version comparison: select two versions and see a field-by-field diff. Additions, deletions, modifications highlighted. * Restoring a previous version creates a new version (never overwrites history). Entry at version 10, restore version 7, entry becomes version 11 with version 7's content. Versions 8-10 remain accessible. * Restoring does not republish. The restored content updates the draft. You must explicitly publish to push changes live. * Previewing future states: standard Live Preview shows a single entry's draft. Time travel preview composites all scheduled changes to show the full site state at a target date. * Three approaches to future-state preview: preview all drafts (simplest), date-parameterized preview (more targeted), or Release-scoped preview (most precise but most code). * Overlapping Releases targeting the same entry on the same date have no automatic conflict resolution. The last one to execute wins. ## Screen: What to Show Outline item What to show on screen Opening (outline items 1-2) Start with the Contentstack entry editor showing a page entry. Toggle from the standard form view to Visual Builder view. Let the iframe load and show your actual frontend appearing inside the CMS. Briefly show the browser DevTools Elements panel with  data-cslp  attributes visible on DOM elements, demonstrating the field-to-DOM mapping. data-cslp tagging (outline item 3) Switch to VS Code. Show a component file with  data-cslp  attributes on elements. Highlight the format:  content\_type\_uid.entry\_uid.locale.field\_path . Show  addEditableTags()  usage: the call to  contentstack.Utils.addEditableTags(entry, "page", true)  and the resulting  entry.$?.title  spread syntax in JSX. Show a modular block component with the index in the field path:  components.${index}.hero.title . Implementation walkthrough (outline item 4) Show the Live Preview SDK initialization code with  mode: "builder" . Point out  clientUrlParams.host ,  editButton.exclude , and the conditional loading pattern. Show the  next.config.js  CSP headers allowing  frame-ancestors 'self' https://app.contentstack.com . Editor experience demo (outline item 5) Back in Visual Builder in the browser. Hover over elements to show highlight overlays appearing. Click on a title and edit it inline. Show the change rendering live. Click on an image field and show the file picker. Select a new image and watch it swap. Edit a rich text block inline. This should be the most visually impressive part of the video. Let it breathe. GraphQL setup (outline item 6) Show the GraphQL preview client code in VS Code. Point out the preview endpoint, the  live\_preview  hash header, and the  onEntryChange  callback with  router.refresh() . Show a  data-cslp  attribute next to a GraphQL query with an alias, and explain that the attribute must use the schema field UID, not the alias. Localization (outline item 7) In Visual Builder, switch the locale dropdown in the Contentstack entry editor. Show the preview iframe updating to render locale-specific content. Show the dynamic locale in a  data-cslp  attribute in code:  page.${entry.uid}.${locale}.title . Releases (outline items 8-9) Navigate to Publish Queue > Releases in the Contentstack UI. Create a new Release, name it descriptively. Add entries to the Release from the entry editor and from the Release detail screen. Show both publish and unpublish actions on items. Show the Veda Holiday Collection Release with its item list: product entries, landing page, navigation update, old campaign page marked for unpublish. Scheduling (outline item 10) Click Schedule Release. Set the environment, date/time, and locale. Show the locked state after scheduling. Show the Publish Queue with pending scheduled items. Versioning and future-state preview (outline item 11) Open an entry's version history. Show the version list with numbers, authors, timestamps. Select two versions and show the diff view with field-level changes highlighted. Demonstrate restoring a version: click Restore, show the new version created, point out the version number incremented. Show the publish queue with scheduled Releases and explain the "time travel" concept. If you have a Release-aware preview endpoint, show the composite future state. ## Veda Scenario Thread Veda is launching the Holiday Collection -- a coordinated campaign touching multiple content types. This thread runs through the entire video: 1. **Visual Builder setup:** Show Veda's kickstart-veda marketing homepage in Visual Builder. The page uses modular blocks (hero, list, rich\_text, two\_column). Demonstrate editing the hero title, a product card from a reference field, and rich text content directly in the rendered page. 2. **Tagging complexity:** Veda's list block stores content in a reference field. The page-level edit tag for the reference picker is page...components.{index}.list.reference, while nested product fields use the referenced entry's own content type and UID (product.{uid}.en-us.title). Walk through this distinction live. 3. **Localization:** Veda operates in multiple locales. Show switching from en-us to another locale in Visual Builder and seeing the localized hero text update. Point out the dynamic locale in data-cslp attributes. 4. **Release assembly:** Veda's Holiday Collection Release includes: homepage with Holiday hero (publish), 8 Digital Dawn products (publish), Digital Dawn product line update (publish), header with "Holiday" menu item (publish), and old campaign page (unpublish). Walk through adding items and reviewing the complete list. 5. **Scheduling the launch:** Schedule the Holiday Collection Release for November 28 at midnight. Show the locked state and the publish queue entry. 6. **Version control during prep:** While preparing the campaign, an editor introduces a typo in a product entry. Show the version history, compare the current version to the previous one, restore the correct version, and verify the fix before re-adding to the Release. 7. **Future-state preview:** Preview what the homepage will look like on November 28 after the Release deploys. All campaign content appears together. The old campaign page is gone. Everything is validated before the scheduled date. ## Transitions 1 to 2: "Now that you know what Visual Builder gives editors, let's look at the architecture that makes it possible." 2 to 3: "The key to that architecture is one HTML attribute: data-cslp." 3 to 4: "Knowing the format is one thing -- let's walk through the full implementation, step by step." 4 to 5: "With everything wired up, here is what the editor actually experiences." 5 to 6: "That was the REST setup. If your frontend uses GraphQL, the setup differs in a few important ways." 6 to 7: "GraphQL covered. Now let's handle localization, because hardcoding en-us will break Visual Builder for every other locale." 7 to 8: "Visual Builder handles the editing experience. But when you need multiple entries to go live together, you need Releases." 8 to 9: "Let's make this concrete with Veda's Holiday Collection launch." 9 to 10: "The Release is assembled. Now we schedule it so everything deploys automatically at the right time." 10 to 11: "Before we wrap up, there is one more operational layer: version control and previewing what the site will look like after a scheduled Release deploys." 11 to closing: "That covers Visual Builder, Releases, and future-state preview. In the next video, we move into workflows, branches, and team collaboration -- the governance layer that keeps all of this organized at scale." ## Common Mistakes to Call Out 1. **Missing** **data-cslp** **on modular block children:** Tagging only the modular block container produces a single large clickable region that opens the full block editor instead of field-level editing. Tag each field individually, including the array index in the field path. 2. **Incorrect field paths for nested content:** Using components.0.title instead of components.0.hero.title for a modular block, or seo\_title instead of seo.meta\_title for a group field. Visual Builder fails silently -- no overlay, no error. Always verify paths against the content type schema. 3. **Deploying Visual Builder SDK to production without conditional loading:** The SDK only activates in the iframe context, but including it in the production bundle adds unnecessary JavaScript weight. Conditionally import based on your preview mode flag. 4. **Using GraphQL aliases in** **data-cslp** **values:** If your query uses heroTitle: title, the data-cslp must still reference title, not heroTitle. Visual Builder resolves against the schema, not your query structure. 5. **Hardcoding locale in** **data-cslp** **for multi-locale sites:** Setting en-us when rendering French content causes Visual Builder to open the English field editor. Always derive the locale dynamically from routing context. 6. **Omitting** **frame-ancestors** **CSP directive on the preview host:** Without it, the browser blocks the iframe entirely. Visual Builder shows a blank panel. This is easily missed because the preview site works when accessed directly in a browser tab. 7. **Adding entries to a Release that have not completed workflow review:** If an entry is stuck in a non-publishable workflow stage when the Release fires, it may be silently skipped or block the entire deployment. Verify workflow stages before scheduling. 8. **Forgetting to include referenced assets in a Release:** Entries go live but render with broken images because the assets were not in the Release and were not already published to the target environment. 9. **Assuming restore republishes content:** Restoring a previous version updates the draft only. The live site continues serving the old content until you explicitly publish. Editors often miss this step. 10. **Previewing individual entries and assuming the full page is correct:** A single entry from a Release renders fine, but a navigation change in the same Release conflicts with the layout. Always validate the composite page state using a Release-aware or all-drafts preview. 11. **Not accounting for overlapping scheduled Releases:** Two Releases modify the same entry on the same date. No automatic conflict resolution exists. The last one to execute wins. Review the publish queue for collisions. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 9 — Visual Builder, Releases, and Future-State Preview** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 11 — Video Production Plan : Video 10 — Workflow, Automation Hub, and Branch Strategy #### Lesson text # Video 10 — Workflow, Automation Hub, and Branch Strategy Attribute Details Course 5 (Workflow, Branches, and Collaboration) Covers Lessons 5.1.1, 5.1.2, 5.1.3, 5.2.1, 5.2.2, 5.2.3, 5.2.4 Priority Core Length 18-24 min Format Screencast (Contentstack UI + diagrams) Status Not started ## Why This Video Matters This is ideal as a single operational overview video because the course is conceptually linked from start to finish. Strong operations make strong models and APIs sustainable. ## Outline 1. Content lifecycle from draft to publish: stages, transitions, permissions 2. Why workflows matter: prevent accidental publishing, enforce review gates, create accountability 3. Walk through creating a Veda workflow: Writer drafts, Editor reviews, Manager approves, auto-publish on approval 4. Workflow rules: who can transition between stages, notification triggers 5. Automation Hub: trigger actions based on workflow transitions (Slack notification, webhook, external system update) 6. Show a practical automation: entry reaches "Approved" stage, notify the frontend team 7. When content branches are the right tool: redesigning a content type without disrupting the live site 8. Compare and merge: reviewing differences between branches, resolving conflicts 9. Parallel development: multiple teams working on different content model changes simultaneously 10. Branch hygiene: naming conventions, lifecycle policies, when to merge and delete ## Key Lines "Workflows turn 'be careful' into 'the system prevents mistakes'." "Branches are not environments, and environments are not branches." "Good workflow design reduces coordination cost without becoming bureaucracy." ## Detailed Talking Points ### 1\. Content lifecycle from draft to publish: stages, transitions, permissions * Every entry lives in exactly one workflow stage at a time: Draft, Review, Approved, Published. * Transitions are explicit actions, not implicit — someone (or an automation) moves the entry forward or backward. * The "Published" stage is set automatically by the system when the publish action completes; you never drag an entry into it manually. * Publishing and workflow status are independent dimensions. An entry can be "Approved" and published to zero environments. Always check both when debugging visibility. * Publish rules tie workflow stages to environments — Draft publishes nowhere, Review publishes to dev/staging, Approved publishes to production. * Unpublishing removes an entry from a delivery environment without deleting it from the CMS. Useful for seasonal content, corrections, and environment-specific visibility. * Bulk workflow operations exist: bulk stage transitions, bulk publish, bulk unpublish — all respecting the same permission rules as individual operations. ### 2\. Why workflows matter: prevent accidental publishing, enforce review gates, create accountability * Without workflows, any user with publish permissions can push any entry to production regardless of readiness. * Workflows turn informal "be careful" policies into enforced system behavior. * Every transition is logged in the audit trail — who moved what, when, and to which stage. * Workflow stages give teams filterable queues: see all entries stuck in Review, identify bottlenecks at a glance. * The goal is reducing coordination cost without creating bureaucracy. Match stage count to team size and content risk. * Without publish rules configured alongside workflows, stages are advisory only — they label but do not prevent. ### 3\. Walk through creating a Veda workflow: Writer drafts, Editor reviews, Manager approves, auto-publish on approval * Navigate to Settings > Workflows, click "Add Workflow." * Define stages in sequence: Draft (gray), Editorial Review (blue), Manager Approval (green). * For each stage, set a name, color, and description explaining what should happen there. * Assign transition permissions: Writers can move Draft to Editorial Review. Editors can move Editorial Review to Manager Approval or reject back to Draft. Managers can approve. * Assign the workflow to the Veda "Product Line" content type. * Configure publish rules: Draft publishes to nothing, Editorial Review publishes to development and staging, Manager Approval publishes to all environments including production. * Show that different content types can have different workflows — a blog post might have a simpler two-stage flow. * Mention superuser bypass: Owners can skip stages for emergencies, but every bypass is logged in the audit trail. ### 4\. Workflow rules: who can transition between stages, notification triggers * Permissions are configured through Settings > Roles, not through the workflow itself. * Each role gets specific workflow permissions: Content Author creates and submits, Editor reviews and forwards or rejects, Manager gives final approval. * These permissions create a chain of responsibility — no role can interfere with another role's part of the lifecycle. * Notification triggers fire when entries move between stages. Reviewers get notified when entries land in their queue. * Workflow assignment can vary by content type — a product monograph might need Legal Review and Compliance stages that a blog post does not. * A common design mistake is building stages that match the org chart rather than the content process. Design around distinct review activities, not job titles. ### 5\. Automation Hub: trigger actions based on workflow transitions * Automation Hub is Contentstack's built-in automation engine — visual flow builder in the Automate section. * It connects CMS events (publish, stage change, asset upload) to actions (Slack messages, Jira tickets, auto-publish) without custom code. * Triggers include: entry created, entry updated, entry published, workflow stage changed, asset uploaded, release deployed. * Triggers should be scoped narrowly to specific content types or environments — a trigger on "any entry published" across all content types generates enormous noise. * Actions can be internal (move to workflow stage, update entry field, publish entry, create task) or external via connectors (Slack, Teams, Jira, Asana, webhook). * Connectors handle authentication, retry logic, and payload formatting — you configure once and reuse across automations. * Conditional logic supports if/then branching based on field values, locale, environment, or user. * Automations execute asynchronously and independently — no guaranteed execution order between multiple automations on the same trigger. ### 6\. Show a practical automation: entry reaches "Approved" stage, notify the frontend team * Create a new automation in the Automate section: "Notify Frontend on Product Approval." * Trigger: Workflow stage changed, scoped to the "Product Line" content type, specifically the "Approved" stage. * Action: Send Slack message to #frontend-deploys with template variables: entry title, content type, user who approved. * Walk through the template variable syntax: double curly braces like {{entry.title}} and {{user.name}}. * Show a second pattern: auto-publish to staging on approval. Trigger on "Approved" stage, action is "Publish entry to staging environment." * Mention the limitation: there is no undo for automation actions. A misconfigured flow that publishes to production prematurely must be reversed manually. * Show where to test the automation before activating it on production content. * Call out that connector auth tokens can expire — monitor connector health proactively. ### 7\. When content branches are the right tool * Branches fork content type schemas, not code. They create parallel versions of your content model. * The problem they solve: how do you restructure a content type without breaking the production site that depends on the current schema? * Without branches, you either break production immediately or coordinate a high-risk synchronized cutover. * Branches include content type definitions, global field definitions, and optionally entries. They do NOT include environments, webhooks, workflows, roles, or Automation Hub configs — those are stack-level. * The main branch is the default for all API queries. Creating a branch changes nothing about production until you merge. * Use branches for: breaking schema changes, new content types needing iteration, large migrations, coordinating frontend and CMS changes. * Do NOT use branches for: content-only changes (use workflow stages), environment isolation (use environments), small non-breaking field additions, or urgent hotfixes. * Critical distinction: branches are NOT environments. Branches control how content is structured. Environments control where content is delivered. ### 8\. Compare and merge: reviewing differences between branches, resolving conflicts * Always use the compare view before merging — it shows field-level additions, removals, and modifications per content type. * Three categories of diff: added content types, modified content types, deleted content types. * Field-level diff shows: fields added, fields removed, fields modified (type changes, validation changes, renames). * Field removal in a merge means permanent data loss on existing entries. There is no undo. * Merge strategies: merge\_prefer\_base (default, keeps target values on conflict), merge\_prefer\_compare (keeps source values), overwrite\_with\_compare, merge\_new\_only. * Merges cannot be automatically reversed. Create a backup branch from the target before merging. * Pre-merge checklist: review all changes, check for field removals, verify existing entries will not break, coordinate with frontend team, communicate with content team, choose timing. * Post-merge: verify content types, test delivery API, deploy frontend, re-publish affected entries, populate new required fields. ### 9\. Parallel development: multiple teams working on different content model changes simultaneously * Multiple branches can exist simultaneously, each serving a different team's schema changes. * Use branch naming conventions: feature/, migration/, redesign/, fix/, experiment/ — signals purpose and expected lifespan. * Point QA builds at specific branches via the branch SDK parameter. Each team tests in isolation. * Merge sequencing matters: merge the smallest and most isolated branch first, then branches modifying fewer content types, then the broadest branch last. * Re-compare against main between each merge — earlier merges change what the next merge encounters. * There is no built-in rebase. If a branch diverges significantly, you create a fresh branch from current main and manually re-apply changes. * Communication is essential: maintain a branch registry, announce merges before and after, inform editors about incoming content type changes. ### 10\. Branch hygiene: naming conventions, lifecycle policies, when to merge and delete * Every branch should follow a defined lifecycle: create, develop, test, merge, delete. * Set time limits: 0-14 days is normal, 14-30 days needs a status update, 30-60 days needs a review, 60-90 days is at-risk, 90+ days is presumed stale. * Assign a single person (tech lead or CMS architect) to own branch governance. Shared responsibility means no responsibility. * Delete branches immediately after a successful merge and post-merge verification. Do not keep them "just in case." * Treat stale branches as technical debt — they accrue interest the longer they sit. * Monitor branch drift periodically for long-lived branches: compare to main to assess divergence. * Abandoned branches create confusion for new team members, waste resources, and increase merge complexity for active branches. * Weekly branch review in standup: two minutes reviewing the branch registry catches sprawl before it develops. ## Screen: What to Show Outline item What to show on screen 1\. Content lifecycle Contentstack entry list view filtered by workflow stage. Show the colored stage labels. Open a single entry and point out the workflow stage indicator. Show the mermaid diagram: Draft > Review > Approved > Published with rejection loops. 2\. Why workflows matter Entry list with 30 entries in Review and 2 in Approved — visual bottleneck. Show the audit log for a workflow transition: who, what, when. Show what happens when you try to publish a Draft entry to production without publish rules (it succeeds — that is the problem). 3\. Veda workflow creation Live screencast in Settings > Workflows. Create a new workflow step by step. Add three stages with colors. Configure transition permissions per role. Assign the workflow to the Product Line content type. Then go to Settings > Workflows > Publish Rules and create rules tying stages to environments. 4\. Workflow rules Settings > Roles screen. Show how a Content Author role is configured with specific workflow permissions. Show the permission matrix: which roles can transition to which stages. Brief shot of a notification email or in-app notification triggered by a stage transition. 5\. Automation Hub Navigate to the Automate section. Show the list of existing automations. Open the flow builder. Show the trigger selector with the list of available CMS events. Show the connector library: Slack, Jira, Teams, webhook. Show the conditional logic branching UI. 6\. Practical automation Build the automation live: select trigger (workflow stage changed to Approved for Product Line), add Slack action, configure channel and message template with curly-brace variables. Hit the test button to simulate. Show the Slack message arriving in the channel. Then show a second automation: auto-publish to staging on approval. 7\. Branches Settings > Branches screen. Create a new branch from main. Show the branch creation form (name, source). After creation, switch to the branch and show the content type list — identical to main at creation time. Modify a content type on the branch (add a field). Switch back to main and show the content type is unchanged. Show the SDK config with the branch parameter. 8\. Compare and merge Open the compare view for the branch vs main. Walk through the diff: added fields in green, removed fields in red, modified fields highlighted. Show the merge strategy selector. Show the confirmation dialog. After merge, open the content type on main and verify the new field is present. 9\. Parallel development Show two or three branches in the branch list, named with conventions (feature/, migration/). Show a CI/CD config snippet with the branch environment variable. Show a QA site rendering content from a branch. Show the branch registry spreadsheet or doc. 10\. Branch hygiene Show a cluttered branch list with old branches. Run the branch audit script (or show its output) — branches flagged by age. Delete a stale branch. Show the clean branch list afterward. Show the time-limit policy table as a slide or overlay. ## Veda Scenario Thread Veda is a direct-to-consumer brand managing product launches across multiple regions. Throughout this video, Veda's operational needs drive every concept: * **Workflow creation (items 1-4):** Veda's content team has writers, regional editors, and a marketing manager. Writers draft product descriptions. Regional editors review for market accuracy and tone. The marketing manager gives final approval before production publish. Build this exact workflow live in the Contentstack UI, using Veda's "Product Line" content type. * **Automation Hub (items 5-6):** When a Veda product page reaches the "Approved" stage, the frontend team needs to know so they can prepare the deployment. Build a Slack notification automation for this. Also show auto-publishing approved content to the staging environment so the marketing manager can preview before the manual production publish. * **Branches (item 7):** Veda's development team needs to add a "specifications" modular block and a "sustainability\_statement" rich text field to the Product Line content type. These are breaking changes — the live site expects the current schema. Create a branch called feature/product-specs-v2, make the changes there, and show that the production site is unaffected. * **Compare and merge (item 8):** After Veda's dev team finishes iterating on the branch, show the compare view between feature/product-specs-v2 and main. Walk through the diff, noting the new fields and confirming no fields were accidentally removed. Execute the merge and verify on main. * **Parallel development (item 9):** Mention that Veda's design team is simultaneously working on a redesign/homepage-hero branch to restructure the homepage into modular blocks. Two branches, two teams, zero interference — because the branches modify different content types. * **Branch hygiene (item 10):** After the merge, delete feature/product-specs-v2 immediately. Show the branch registry entry being marked as merged and the branch being removed from the list. Reference Veda's policy: branches older than 30 days get reviewed, branches older than 60 days get escalated. ## Transitions 1 to 2: "That is the lifecycle — now let us talk about why encoding it into the system matters more than telling your team to be careful." 2 to 3: "So let us build this in Contentstack — here is what a real workflow looks like for Veda's product content." 3 to 4: "The stages are set up, but who gets to push content through each gate — that is where role-based permissions come in." 4 to 5: "Manual transitions work, but what if the system could react automatically when content moves between stages?" 5 to 6: "Let me show you a concrete example — we will wire up a Slack notification that fires the moment a Veda product gets approved." 6 to 7: "Workflows handle the content lifecycle. But what about the content model itself — what happens when you need to change the structure without breaking production?" 7 to 8: "You have made your changes on a branch. Now you need to get them back to main — and that is where compare and merge earns its keep." 8 to 9: "One branch is straightforward. But what happens when three teams each have their own branch running at the same time?" 9 to 10: "Parallel branches work great until they do not — let us talk about the discipline that keeps branches from becoming a liability." 10 to Video 11: "Workflows, automations, and branches give you operational control over your content model. In the next video, we shift to the developer experience — webhooks, extensions, and building custom integrations on the Contentstack platform." ## Common Mistakes to Call Out 1. **Confusing workflow stage with publish state.** An entry in "Approved" is not published. An entry that is published is not necessarily in the "Published" workflow stage. These are two separate systems — workflow tracks editorial readiness, publishing controls delivery availability. Always check both dimensions. 2. **Skipping review for "small changes."** Typo fixes are how broken links, deleted paragraphs, and accidental field clears reach production. The workflow exists to catch mistakes, and mistakes do not scale with perceived change size. 3. **Creating workflow stages without configuring publish rules.** Without publish rules, stages are advisory only — a Draft entry can still be published to production. Workflows and publish rules must be configured together. 4. **Creating stages without assigning role-based permissions.** A workflow stage without permissions is just a label. If anyone can move an entry to "Approved," the stage provides no governance. 5. **Building workflows that match the org chart instead of the content process.** If "VP Review" and "Director Review" check the same things, merge them into one stage. Design around distinct review activities, not job titles. 6. **Not scoping Automation Hub triggers to specific content types.** A trigger on "any entry published" fires for every content type in the stack. If you only care about blog posts, the automation runs unnecessarily for every other publish event. 7. **Building automations that depend on execution order.** Multiple automations on the same trigger have no guaranteed execution order. If one sets a field value and another reads it, the reader may execute first. Put sequential operations in a single automation flow. 8. **Treating Contentstack branches like git branches.** Git branches create parallel code files and merge line-by-line. Contentstack branches fork content type schemas and merge at the field level. The mental model, merge mechanics, and conflict resolution are all different. 9. **Creating branches for content editing instead of schema changes.** If editors want to draft entries without affecting the live site, they need workflow stages and publish rules, not branches. Branches are for content model changes only. 10. **Forgetting that stack-level settings are not branched.** Environments, webhooks, workflows, roles, and Automation Hub configs are shared across all branches. Modifying a webhook affects events on every branch. 11. **Merging without reviewing the compare diff.** Every merge can remove fields, delete content types, and destroy data. Merging without reviewing the diff is deploying without reading the pull request. 12. **Forgetting that field removal means permanent data loss.** When a merge removes a field from a content type, all data in that field on existing entries is gone. There is no undo. 13. **Not coordinating merges with frontend deployments.** A merge that changes the API response shape without a frontend update breaks the site. Plan merges and frontend deployments as a coordinated operation. 14. **Keeping merged branches "just in case."** After a merge, the branch contains no unique information. If you need a backup, create a backup branch from main before merging, not after. Delete the source branch once the merge is verified. 15. **No single person responsible for branch governance.** When branch management is everyone's responsibility, it is no one's responsibility. Designate one person to own branch hygiene. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 10 — Workflow, Automation Hub, and Branch Strategy** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 12 — Video Production Plan : Video 11 — When To Customize: Configuration vs Apps vs Webhooks #### Lesson text # Video 11 — When To Customize: Configuration vs Apps vs Webhooks Attribute Details Course 6 (Extending and Customizing Contentstack), Module 6.1 Covers Lessons 6.1.1, 6.1.2, 6.1.3, 6.1.4 Priority Critical Length 18-25 min Format Screencast (Developer Hub + code editor) Status Not started ## Why This Video Matters This is a high-value decision video. Every customization creates long-term ownership cost. The right question is not whether you can build it, but whether you should own it. ## Outline 1. Configuration vs customization: always try configuration first; customize only when configuration cannot solve the problem 2. The decision framework: when to use native features, marketplace apps, custom apps, or webhooks 3. Marketplace apps: browse, install, and configure pre-built integrations — show a few useful examples 4. Building custom apps: Developer Hub, App SDK, UI locations (custom fields, sidebar widgets, dashboard widgets, full-page apps) 5. Walk through building a simple custom field or sidebar widget 6. App hosting options: self-hosted vs Contentstack-hosted 7. Webhooks: event-driven integration — trigger external systems when content changes 8. Show creating a webhook, configuring trigger conditions, and handling the payload 9. Webhook security: verifying signatures, handling retries, idempotency 10. Examples of over-customization and how to avoid it ## Key Lines "Every customization creates long-term ownership cost." "The right question is not whether you can build it, but whether you should own it." "Built-in features usually age better than custom code." ## Detailed Talking Points ### 1\. Configuration vs customization: always try configuration first * Contentstack ships with field validation rules, workflow stages, publish rules, roles and permissions, taxonomies, and Automation Hub connectors. Most teams underestimate how much this covers. * Field validation alone handles required fields, unique constraints, regex patterns, character limits, number ranges, and select-field options — all without code. * Workflow stages let you enforce multi-step approval (Draft > Review > Legal > Published) with role-based gates. If the ask is "editors need approval before publishing," the answer is a workflow, not an app. * Publish rules restrict who can publish to which environment. Roles and permissions give you per-content-type, per-environment, per-locale control. * Automation Hub provides no-code connectors for common triggers — Slack notifications, simple data syncs — without a webhook handler to deploy or monitor. * The core principle: every custom integration adds hosting, monitoring, and maintenance cost that compounds over its lifetime. Configuration has effectively zero ongoing cost. ### 2\. The decision framework * Walk through six levels before writing any code: (1) field validation, (2) workflow stage, (3) publish rule or role, (4) Automation Hub, (5) webhook, (6) custom app. * Each level up the ladder adds maintenance cost. Field validation is free. A custom app requires hosting, monitoring, SDK updates, documentation, and onboarding. * Show the table from the lesson: initial development time, hosting, monitoring, dependency updates, documentation, onboarding, platform upgrades — compare custom app vs webhook vs configuration. * Stress the two-year total cost of ownership lens. A three-day build can cost three hours per quarter to maintain — dependency updates, SDK bumps, deployment fixes. * The worked example: "every blog post needs at least three taxonomy tags before publishing." Walk the framework level by level to show how you land on a lightweight sidebar widget only after configuration falls short. ### 3\. Marketplace apps: browse, install, configure * The Marketplace lives in the left nav of any stack. Two categories: Contentstack-built apps (Algolia, Commercetools, Salesforce, Bynder, Cloudinary) and custom/private apps. * Installing is stack-specific — installing in dev does not install in production. * Walk through installing a pre-built integration: browse the catalog, click Install, review OAuth scopes on the consent screen, configure via the App Configuration page, and the app appears in its defined locations. * Call out concrete examples: Bynder DAM for asset management, Cloudinary for image transformation, Typeform for embedding forms. * Emphasize that pre-built apps are maintained by Contentstack or the vendor — you do not own the maintenance burden. ### 4\. Building custom apps: Developer Hub, App SDK, UI locations * Apps run in sandboxed iframes. Your code is served from your hosting; Contentstack loads it in an iframe and communicates via the App SDK's postMessage bridge. * Six UI locations: Custom Field, Sidebar Widget, Dashboard Widget, Full-Page App, Asset Sidebar, and App Configuration. Each receives different contextual data. * Custom Field: replaces a standard field, owns a JSON value stored in the entry and returned via Delivery API. Think color pickers, product selectors, location pickers. * Sidebar Widget: appears in the right sidebar, reads/modifies the entire entry but does not own a field. Think SEO scorers, translation trackers, quality checklists. * Dashboard Widget: lives on the stack dashboard for at-a-glance info. Think content calendars, publishing feeds, task queues. * Full-Page App: gets its own left-nav item, occupies the full content area. Think analytics dashboards, bulk operations tools, migration interfaces. * RTE Plugin: extends the Rich Text Editor with custom toolbar buttons or content blocks. * App Configuration: the settings UI that stack admins see when installing the app — store API keys, feature toggles, mapping configs here instead of hardcoding. ### 5\. Walk through building a simple custom field or sidebar widget * Start in Developer Hub: create a new app, name it descriptively ("PIM Product Selector," not "Custom Field 1"), select locations, set OAuth scopes. * Scaffold the project: csdx app:create generates a React project with the App SDK pre-installed and location-specific component stubs. * Core pattern: call ContentstackAppSdk.init() (async), get the location-specific interface, read data, render UI, write data back. * For a Custom Field: field.getData() to load, field.setData(value) to save. The JSON you write is exactly what the Delivery API returns. * For a Sidebar Widget: sidebar.entry.getData() reads the full entry, sidebar.entry.onChange() listens for real-time changes. * Test locally: point the location URL in Developer Hub to http://localhost:3000, install in a dev stack, open an entry, see your app in the iframe. * Stress the data contract: whatever JSON shape you write to a Custom Field is consumed by every frontend. Treat it as a versioned API contract — changing it after entries are published breaks consumers. ### 6\. App hosting options: self-hosted vs Contentstack-hosted * Self-hosted: deploy to Vercel, Netlify, AWS S3 + CloudFront, or any static/server hosting. You manage HTTPS, deployment, uptime, and scaling. * Contentstack Launch: Contentstack hosts your app for you. You get HTTPS, deployment, and no infrastructure to manage. This is the path of least resistance for most internal apps. * Trade-off: self-hosted gives you full control (custom domains, edge functions, specific CDN config). Contentstack-hosted removes operational overhead but limits infrastructure customization. * For most certification-level apps and internal tools, Contentstack-hosted is the right default. ### 7\. Webhooks: event-driven integration * Webhooks reverse the API direction: instead of your code calling Contentstack, Contentstack calls your endpoint when something happens. * Configured under Settings > Webhooks. You provide a name, an HTTPS URL, optional custom headers, and select which events trigger it. * Events are organized by resource: entries (create, update, publish, unpublish, workflow), assets (upload, update, delete, publish), content types (create, update, delete), releases (create, deploy). * You can scope to specific content types — a search indexing webhook might only fire on publish/unpublish for Product and Product Line. * Common use cases: search index updates, cache invalidation, notification systems, data sync to commerce/ERP, static site rebuild triggers, audit logging. ### 8\. Show creating a webhook, configuring trigger conditions, and handling the payload * In the UI: Settings > Webhooks > New Webhook. Name it clearly ("Algolia Product Index Update on Publish"). * Select events: check content\_types.entries.publish and content\_types.entries.unpublish. Scope to the Product content type. * Set retry policy: 3-5 retries, 60-second delay. A "failure" is a non-2xx response or timeout. * Walk through the payload structure: event (e.g., content\_types.entries.publish), triggered\_at, triggered\_by, event\_data.entry (the full entry snapshot), event\_data.content\_type, event\_data.environment, event\_data.locale. * Show a real handler: receive the POST, parse the JSON, extract entry data, update the external system. ### 9\. Webhook security: verifying signatures, handling retries, idempotency * Contentstack signs every webhook request and sends signature metadata in headers: X-Contentstack-Request-Signature, X-Contentstack-Request-Timestamp, X-Contentstack-Request-Version. * Your handler fetches the webhook public key from Contentstack's public key endpoint and verifies the signature against the raw request body. * Critical: use the raw request body for verification. If your framework parses JSON first, the bytes change and verification fails. * Validate timestamp freshness to prevent replay attacks. * Idempotency: webhooks are "at least once," not "exactly once." Use a deduplication key (entry UID + event type + timestamp) to skip duplicates. * Respond with 200 immediately, then process asynchronously. If you process synchronously and it takes too long, Contentstack retries, creating duplicates. * For robust async: enqueue the payload to SQS, Pub/Sub, or RabbitMQ and process from a worker. ### 10\. Examples of over-customization and how to avoid it * Character-limit validation app: a team builds a sidebar widget to check meta description length. Contentstack field validation already has min/max character limits. The custom app duplicates built-in functionality and now needs hosting. * Slack notification webhook handler: a developer writes a Node.js Lambda + API Gateway + CloudWatch stack to send a Slack message on publish. Automation Hub does this with a visual connector in under five minutes, no code. * Custom dropdown field: a team builds a Custom Field app for a country dropdown because the list is "dynamic." If the list changes once a year, a Select field with a content model update is cheaper. * Custom workflow engine: a team writes middleware for approval stages, email notifications, and role gates. Contentstack's built-in workflow handles all of this natively. The custom engine creates a parallel system editors must learn. * The pattern: always ask "can built-in features handle this?" before writing code. The answer is "yes" more often than developers expect. ## Screen: What to Show Segment What is on screen Configuration vs customization (items 1-2) Content type builder with field validation settings open. Show a regex validation rule on a SKU field. Then show the Workflow editor with multi-stage approval flow. Decision framework (item 2) Split-screen or overlay graphic showing the six-level ladder: field validation > workflow > publish rule/role > Automation Hub > webhook > custom app. Highlight cost increasing at each level. Marketplace apps (item 3) Contentstack Marketplace catalog in the left nav. Browse the catalog, click into Bynder or Cloudinary, show the install flow, OAuth consent screen, and App Configuration page. Building custom apps (items 4-5) Terminal: run csdx app:create, show the scaffolded project structure. VS Code: open the Custom Field component. Developer Hub: show the app registration with locations and URLs. Contentstack entry editor: show the custom field rendering in the iframe. App hosting (item 6) Developer Hub app settings showing the location URL field. Show switching from localhost:3000 to a Contentstack Launch deployed URL. Webhooks (items 7-8) Settings > Webhooks in the Contentstack UI. Create a new webhook, select events, scope to a content type. Then show the webhook logs with delivery attempts and status codes. Webhook handler code (items 8-9) VS Code with the Express handler open. Walk through the signature verification block, the immediate 200 response, and the async processing function. Highlight the deduplication key pattern. Over-customization (item 10) Side-by-side: left shows the custom app code and deployment config, right shows the equivalent built-in feature configured in under a minute. Make the contrast visual and obvious. ## Veda Scenario Thread Veda (the fictional jewelry brand) runs through this video as the connective tissue: * **Configuration first:** Veda's content team asks for SKU validation on product entries. Show configuring a regex rule (^VDA-\[A-Z0-9\]{4}-\[A-Z0-9\]{2}$) directly in the content type builder — no code, done in 30 seconds. * **Marketplace app:** Veda uses Bynder for digital asset management. Show browsing the Marketplace, installing the Bynder app, and configuring it so editors can search Bynder assets from within entries. * **Custom app:** Veda's editors need to pull product data from their PIM system into entries. No marketplace app exists for their PIM. Show registering a Custom Field app in Developer Hub, scaffolding with the CLI, and building a product selector that queries the PIM API and writes structured JSON to the entry field. * **Webhook:** when a Veda product is published, the search index needs updating. Show creating a webhook scoped to the Product content type's publish event, pointing to an Algolia update handler, and walking through the handler code. * **Webhook security:** show verifying the webhook signature in the handler so only legitimate Contentstack requests trigger index updates. * **Over-customization check:** Veda's dev team proposes building a custom sidebar widget to warn when meta descriptions exceed 160 characters. Pause and show that field validation already handles this — cancel the custom build and configure the character limit instead. ## Transitions 1. **Intro to configuration:** "Before we write any code, let's look at how much Contentstack handles out of the box." 2. **Configuration to decision framework:** "So configuration covers a lot — but how do you know when it is not enough? That is where the decision framework comes in." 3. **Decision framework to Marketplace apps:** "If configuration falls short, the next question is: has someone already built what you need?" 4. **Marketplace apps to custom apps:** "When the Marketplace does not have what you need, you build it yourself — and Contentstack gives you a clean developer workflow for that." 5. **Custom app walkthrough to hosting:** "You have got a working app locally — now where does it live in production?" 6. **Hosting to webhooks:** "Apps handle the UI side. For server-side reactions to content events, you use webhooks." 7. **Webhook creation to webhook security:** "A working webhook is step one. A secure webhook is the real requirement." 8. **Webhook security to over-customization:** "Now that you know how to build all of this, here is the most important skill: knowing when not to." 9. **Over-customization to closing:** "Every customization is a commitment. Use the decision framework, start with configuration, and only build what you genuinely need to own." 10. **Closing to Video 12:** "In the next video, we move from extending the platform to deploying what you have built — hosting, environments, and release management with Contentstack Launch." ## Common Mistakes to Call Out 1. **Jumping straight to code without evaluating configuration.** The most frequent error. Every customization decision should start with "can built-in features handle this?" and only proceed to code when the answer is definitively no. Show the decision framework ladder and make viewers internalize the habit. 2. **Forgetting to call** **ContentstackAppSdk.init()** **before accessing data.** The SDK initialization is asynchronous. Accessing sdk.location before init() resolves produces undefined values and silent failures. Gate your UI rendering on initialization completing. 3. **Requesting excessive OAuth scopes.** An app that only reads entry data should not request write scopes. Follow the principle of least privilege — excessive scopes trigger security concerns and may cause admins to reject the install. 4. **Assuming all app locations have the same context.** A Sidebar Widget has entry.getData(). A Dashboard Widget does not — there is no "current entry" on the dashboard. Always check which location is active before calling location-specific methods. 5. **Changing a Custom Field's JSON shape after entries are published.** The data your Custom Field writes is consumed directly by frontend applications via the Delivery API. Changing that shape breaks every consumer. Treat it as a versioned API contract. 6. **Processing webhooks synchronously before responding 200.** If your handler does a database write, an API call, and a cache purge before responding, any step can time out. Contentstack retries, and you get duplicates. Respond immediately, process async. 7. **Skipping webhook signature verification.** Without verifying request signatures, your endpoint accepts requests from any source. An attacker who discovers the URL could trigger index deletions, cache purges, or data corruption. 8. **Not accounting for duplicate webhook deliveries.** Webhooks are "at least once," not "exactly once." Without idempotent processing using a deduplication key, duplicate deliveries create duplicate records or repeated side effects. 9. **Hardcoding stack-specific values in app code.** API keys, content type UIDs, environment names, and service URLs belong in App Configuration, not in your source code. The same app should work across stacks without modification. 10. **Building for imagined future requirements.** "We might need a PIM integration someday" is not a reason to build one today. Apply YAGNI — build when the requirement is concrete and funded, not hypothetical. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 11 — When To Customize: Configuration vs Apps vs Webhooks** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 13 — Video Production Plan : Video 12 — Maintainability, Governance, and Long-Term Ownership #### Lesson text # Video 12 — Maintainability, Governance, and Long-Term Ownership Attribute Details Course 6 (Extending and Customizing Contentstack), Module 6.2 Covers Lessons 6.2.1, 6.2.2, 6.2.3 Priority Polish Length 12-18 min Format Slides + talking head (more conceptual) Status Not started ## Why This Video Matters This is where the platform shifts from implementation to stewardship. Most platform pain appears after launch, not during the initial build. ## Outline 1. Designing for maintainability: future-you (or your replacement) will inherit every decision you make today 2. Documentation that actually helps: document the "why", not just the "what" 3. Technical debt in CMS context: unused content types, orphaned fields, undocumented webhooks, custom apps with no owner 4. Monitoring webhook health and app dependencies 5. Governance enables velocity: naming conventions, review processes, ownership assignments 6. Audit checklist: what to review quarterly 7. Runbooks and operational ownership ## Key Lines "Most platform pain appears after launch, not during the initial build." "Reliability patterns are part of the design, not an afterthought." "The best CMS implementations are boring. They just work, year after year." ## Detailed Talking Points ### 1\. Designing for maintainability: future-you inherits every decision * Open with the core truth: the webhook handler you deploy today will still be running eighteen months from now, long after you have forgotten why you made specific choices. Future-you, or whoever replaces you, reads your code with zero context. * Single responsibility for integrations: one handler does one thing. Three 200-line handlers beat one 3,000-line "platform." When the Algolia indexer needs a change, you touch one directory. Slack notification breaks? Different directory. Failures stay isolated. * Show the folder structure contrast: three focused handler directories versus the monolithic "integration platform" with its routing config, adapter abstractions, middleware layers, and admin UI. Same three requirements, ten times the code. * YAGNI is your friend. Do not build a generic webhook framework when you need three specific handlers. Do not wrap the App SDK in "your custom SDK wrapper" -- that just forces the next developer to learn two APIs instead of one. * Naming is the cheapest form of documentation. "webhook-handler-2" tells you nothing. "algolia-product-index-on-publish" tells you everything without opening a file. Apply this to webhooks, endpoints, environment variables, handler functions, config files. * Dependency management matters: every npm package is a maintenance commitment. Security patches, breaking changes, abandoned maintainers, supply chain risk. A webhook handler that calls one API does not need lodash, moment, axios, and an ORM. * Pin your versions. Commit lockfiles. Schedule monthly or quarterly dependency reviews. ### 2\. Documentation that actually helps: document the "why" * The code explains the what. Documentation should explain the why -- the business requirement, the design decision, the thing that disappears when the original developer leaves. * Every integration needs a README answering five questions: What does it do? Why does it exist? How do I deploy it? What Contentstack settings does it depend on? How do I troubleshoot it? * Content model documentation is not about listing fields -- the UI already shows that. Document the reasoning: why author is a Reference field instead of a Group field, why body uses JSON RTE instead of Markdown, why legacy\_promo\_banner still exists and when it can be removed. * Decision records prevent repeated debates. When you choose JSON RTE over Markdown, write down why so the next developer does not re-litigate the decision. * Webhook routing documentation: a single table showing every webhook, its events, target content types, handler URL, and owner. Without this, understanding the integration landscape requires clicking through every webhook in the Contentstack UI. * Environment topology documentation: which environments serve which frontends, which tokens are in use, where tokens are stored. One page that a new developer reads on day one. ### 3\. Technical debt in CMS context * Technical debt in CMS projects is sneaky. Nobody files a ticket saying "our webhook handler is now unmaintainable." It accumulates entry by entry, dependency by dependency, undocumented decision by undocumented decision. * Content type debt: fields added for a campaign, used once, never removed. legacy\_banner\_text sitting in Article with no validation, no documentation, no entries using it -- but nobody deletes it because "something might depend on it." * Orphaned content types created for features that never launched. Inconsistent field naming across types -- hero\_image here, banner\_image there, main\_image somewhere else. * Integration debt: webhook handlers nobody understands, custom apps on unmaintained framework versions, hardcoded stack UIDs and content type UIDs, undocumented Automation Hub flows. * Configuration drift: the README says one thing, the deployed environment says another. Deployment docs reference a CI/CD pipeline that was replaced three months ago. * The bus factor problem: if the developer who built the Algolia webhook handler is unavailable tomorrow, can someone else debug a delivery failure, deploy a fix, and verify the index? If the answer is no, your bus factor is one. ### 4\. Monitoring webhook health and app dependencies * Without monitoring, failures are silent. Your search index drifts out of sync, Slack notifications stop, cache purges stop working, and nobody notices until an editor reports stale content. * Every handler needs error tracking (Sentry, Datadog, or equivalent). Every unhandled error should trigger an alert. * Health checks: expose a GET /health endpoint, monitor it with an uptime service. * Webhook delivery monitoring: regularly check the webhook logs in Contentstack UI under Settings > Webhooks > \[Webhook Name\] > Logs. Look for non-200 status codes. * A 50-line handler can fail just as silently as a 5,000-line application. Monitoring is proportional to impact, not to code complexity. ### 5\. Governance enables velocity: naming conventions, review processes, ownership * Governance has a reputation problem. Developers hear it and think approval committees and two-week lead times. But the absence of governance creates a different kind of slow: conflicting content type changes, scattered tokens, orphaned webhooks, production publishes that break frontends. * Good governance answers: "who can do what, and how do we stay coordinated?" When those agreements are clear, teams move faster. * Content type governance: content type changes are schema changes. Adding a field changes the API response for every entry. Removing a field can break frontends. Renaming a field UID breaks every query referencing it. * Token governance: delivery tokens in environment variables, never in client-side code. Management tokens exclusively in a secrets manager. Rotate management tokens quarterly and immediately when someone leaves. * Use Contentstack roles to enforce governance automatically. Restrict production publish to specific roles. Junior editors publish to staging only. Do not rely on people remembering policies. * When governance becomes a bottleneck: if field additions take more than one business day, if developers avoid proposing improvements, if the process has more steps than the actual work -- loosen it. ### 6\. Audit checklist: what to review quarterly * Run a quarterly audit of every custom integration: 30 to 60 minutes with a structured checklist. * Ownership: who maintains this? If they left tomorrow, could someone else take over? Is the owner documented? * Dependencies: are they current? Any deprecated or abandoned? Run npm audit for known vulnerabilities. * Tests: do they still pass? Do they cover current behavior, or have features been added without test updates? * Deployment: is the process documented? Can a new team member deploy without asking the original developer? * Contentstack configuration: does the webhook config still match the handler's expected events? Has the content type schema changed? * Monitoring: is error alerting active? Check webhook logs for delivery failures. Has anyone looked at the dashboards this quarter? * Prioritize findings: security findings first, silent failures next, documentation gaps this quarter, technical improvements when capacity allows. ### 7\. Runbooks and operational ownership * A runbook tells you exactly what to do when something goes wrong. Unlike documentation that explains how things work, a runbook is a step-by-step procedure for a specific scenario. * Runbook for re-triggering a failed webhook: navigate to webhook logs, find the failed delivery, copy the payload, verify the handler is healthy, replay with curl including signature headers, verify processing. * Runbook for reindexing search after bulk publish: verify the bulk publish is complete, run the full reindex script with the right environment variables, verify the index record count. * Runbook for deploying a new Marketplace app version: pre-deployment checklist (tests pass, tested in dev stack, SDK compatible, no breaking data format changes), build, deploy, verify in the Contentstack UI, know your rollback path. * Runbooks raise the bus factor. When the procedure is written down, anyone on the team can handle the incident. ## Screen: What to Show * **Outline item 1 (Maintainability):** Show the focused handler folder structure side-by-side with the monolithic "integration platform" folder structure. Highlight the line counts and file counts. If possible, show a real handler file under 200 lines to demonstrate how readable a focused handler is. * **Outline item 2 (Documentation):** Show an example integration README with the five-question structure filled in. Show a content model decision record for the Article content type. Show a webhook routing table in Markdown. * **Outline item 3 (Technical debt):** In the Contentstack UI, navigate to a content type with deprecated fields (or a mock one). Point at fields that look abandoned. Show the content type list and highlight types that might be orphaned. Show the webhook list with poorly named webhooks like "My Webhook" or "Handler 3." * **Outline item 4 (Monitoring):** Show the Contentstack webhook logs screen (Settings > Webhooks > \[Webhook Name\] > Logs). Point at delivery status codes. Show what a failed delivery looks like versus a successful one. Briefly show a Sentry or Datadog error dashboard for a handler. * **Outline item 5 (Governance):** Show the Contentstack Roles screen with a custom role configuration. Show publish rules under Settings > Publish Rules. Show the environment list and explain the mapping to frontends. * **Outline item 6 (Audit):** Show the audit checklist as a document or checklist template. Walk through one integration as a live audit example -- check ownership, dependencies, tests, deployment docs, monitoring. * **Outline item 7 (Runbooks):** Show a runbook document. Walk through the "re-trigger a failed webhook" runbook step by step, showing each screen in the Contentstack UI as you go. ## Veda Scenario Thread Veda has been building custom integrations throughout the course: webhook handlers for Algolia indexing, a PIM Product Selector Marketplace app, Automation Hub flows for notifications. Now she faces the reality that these integrations need to survive beyond her involvement. * **Maintainability:** Veda refactors her monolithic webhook handler into three focused handlers -- one for product indexing, one for Slack notifications, one for CDN cache purging. She applies descriptive naming to each webhook in the Contentstack UI. * **Documentation:** Veda writes READMEs for each handler using the five-question template. She documents why the product content type uses a Reference field for brand instead of embedding it. She creates a webhook routing table covering all of Veda Jewelry's integrations. * **Technical debt:** Veda runs an audit and discovers a legacy\_promo\_banner field on the Article content type from a campaign six months ago, two orphaned webhooks pointing at a decommissioned staging URL, and an Automation Hub flow that nobody remembers creating. She cleans them up. * **Monitoring:** Veda adds error tracking to each handler and sets up health check monitoring. She catches a silent failure in the CDN cache purge handler that had been failing for two weeks without anyone noticing. * **Governance:** Veda establishes lightweight governance for her growing team: content type changes proposed in a Slack channel, production webhooks require a brief review, management tokens stored in AWS Secrets Manager with quarterly rotation. * **Audit and runbooks:** Veda creates the quarterly audit checklist and writes runbooks for the three most common operational scenarios: re-triggering a failed webhook, reindexing Algolia after a bulk publish, and deploying a new version of the PIM Product Selector app. The thread shows Veda transitioning from builder to steward -- the integrations she built now have documentation, monitoring, ownership, and operational procedures that let her team handle incidents without depending solely on her. ## Transitions 1. **Opening to Item 1 (Maintainability):** "Building integrations is the easy part -- keeping them running and understandable twelve months later is where most teams struggle, so let's start with what maintainable code actually looks like in Contentstack." 2. **Item 1 to Item 2 (Documentation):** "Clean code structure gets you halfway there, but without documentation that explains the decisions behind the code, the next developer is still guessing." 3. **Item 2 to Item 3 (Technical debt):** "Even with good docs, debt accumulates -- let's look at the specific forms it takes in CMS projects and how to spot it before it becomes critical." 4. **Item 3 to Item 4 (Monitoring):** "Identifying debt is reactive -- monitoring lets you catch problems as they happen instead of discovering them during an audit." 5. **Item 4 to Item 5 (Governance):** "Monitoring tells you when things break, but governance prevents the conditions that cause breakage in the first place." 6. **Item 5 to Item 6 (Audit):** "Governance sets the rules -- the quarterly audit is how you verify the rules are being followed and the platform is still healthy." 7. **Item 6 to Item 7 (Runbooks):** "The audit finds problems, but when something breaks at 2 AM, you need a runbook that tells you exactly what to do without thinking." 8. **Closing to Video 13:** "You now know how to keep your platform healthy over time -- in the next video, we wrap the entire course with a review and point you toward the certification exam." ## Common Mistakes to Call Out * **Building abstractions too early.** The rule of three applies: do not extract a framework until you have three concrete cases sharing a pattern. Two webhook handlers do not justify a webhook framework. * **Treating "it might change" as a reason to add configuration.** If the Algolia index name has been "products" for two years, hardcode it. Add configuration when the value actually needs to vary, not before. Every config option is a decision the next developer must understand. * **Skipping monitoring because the integration is "simple."** A 50-line handler fails just as silently as a 5,000-line app. If the handler stops working, content and search drift apart, and the problem compounds with every publish. * **Documenting everything at the wrong level of detail.** A 50-page document explaining every line of code is as useless as no documentation. Document the why, the how-to-deploy, and the how-to-troubleshoot. The code explains the what. * **Treating technical debt as something to fix "when we have time."** Teams never have time. Debt compounds. A field that should have been removed six months ago now has entries using it by accident. Allocate explicit, recurring capacity -- one hour per week, one day per sprint, or a quarterly cleanup day. * **Assuming the Contentstack UI is sufficient documentation for webhook routing.** The UI shows individual configs but not the full picture of how all webhooks, automations, and external integrations interact. Write the routing table. * **Applying uniform governance to all stacks.** Development stacks are sandboxes -- let developers experiment. Production stacks need tighter controls. Differentiate governance by stack purpose. * **Governing content creation instead of infrastructure.** Editors do not need permission to create entries. Governance applies to content types, webhooks, tokens, environments, and app installations -- the things that affect platform structure and reliability. * **Management tokens in** **.env** **files or shared via Slack.** A single leaked management token grants full read-write access. Store them exclusively in a secrets manager and rotate immediately when someone with access leaves. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 12 — Maintainability, Governance, and Long-Term Ownership** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 14 — Video Production Plan : Video 13 — Contentstack in a Composable DXP #### Lesson text # Video 13 — Contentstack in a Composable DXP Attribute Details Course 7 (Integrations and the Composable DXP) Covers Lessons 7.1.1, 7.1.2, 7.1.3, 7.2.1, 7.2.2, 7.2.3 Priority Polish Length 15-22 min Format Slides/diagrams + demos where possible Status Not started ## Why This Video Matters Strong closing video that helps learners place Contentstack inside a broader architecture. Zooms out from implementation details to system-level thinking. ## Outline 1. CMS as system of record: Contentstack owns content; other systems own commerce, search, analytics, auth 2. Draw the boundary: what lives in the CMS vs what lives in external systems 3. Integration patterns: event-driven (webhooks), API-mediated (pull), middleware/orchestration layer, batch 4. When to use each pattern — decision framework based on latency needs, data volume, and coupling tolerance 5. Contentstack Launch: hosting and deployment platform — when to use it vs Vercel/Netlify/custom hosting 6. Show a deployment flow: content publish triggers build, build deploys to hosting 7. Automate and Personalize: built-in tools for content automation and audience targeting 8. AI-assisted workflows: how AI features integrate into the editorial process 9. The developer role in AI-enabled operations 10. Where the platform is heading: composable DXP, MACH architecture ## Key Lines "Composable does not mean everything belongs everywhere." "System boundaries are one of the most important architecture decisions in a CMS implementation." "AI changes the workflow, but it does not remove developer responsibility." ## Detailed Talking Points ### 1\. CMS as system of record * Contentstack is the system of record for content — editorial text, images, structured data that content teams create and manage through a publish workflow. * Commerce platforms own pricing, inventory, and transactions. Search platforms own indexes. Analytics platforms own behavioral data. Auth systems own user identity. * The core question: who creates and maintains this data? If editors create it through an editorial workflow, it belongs in the CMS. If it is system-generated, transactional, or changes faster than editorial workflows can accommodate, it belongs elsewhere. * Show the decision framework table: product descriptions (CMS), product prices (commerce), inventory (ERP), blog articles (CMS), user profiles (auth), session data (app server). * "Every content platform eventually becomes a dumping ground if nobody draws clear boundaries." ### 2\. Draw the boundary: CMS vs external systems * Walk through a concrete retail example: Contentstack holds product marketing pages, category landing pages, blog articles, navigation, promotional banners. Shopify holds variants, SKUs, pricing, cart, checkout, customer accounts. ERP holds purchase orders, fulfillment, returns. * The connection between systems is a shared identifier — a shopify\_handle or sku field in Contentstack that links editorial content to the commerce product. It does not create a live connection; the frontend uses it to correlate data at render time. * Explain the hybrid composition pattern: the frontend fetches editorial content from Contentstack and transactional data from external APIs, combining them at render time. Each system stays authoritative for its own data. * Stress ownership clarity: if it is unclear who owns a piece of data, that is a design problem you need to solve before writing any code. ### 3\. Integration patterns * Three patterns cover virtually all CMS integrations: event-driven (webhooks), API-mediated (runtime composition), and batch sync (scheduled jobs). They are complementary, not competing. * Event-driven: Contentstack fires an HTTP POST when something happens (entry published, workflow stage changed). Your handler reacts — updates a search index, invalidates a cache, sends a notification. * API-mediated: the frontend calls multiple APIs at render time and composes them into a single page. No data is copied between systems. Each system remains authoritative. * Batch sync: a scheduled process reads data from a source, transforms it, and writes it to a target. Useful for large data volumes, initial loading, systems that do not support events. * Most real projects use all three for different integration points within the same architecture. ### 4\. When to use each pattern — decision framework * Three factors drive the choice: how quickly the target needs to reflect changes, how much data moves, and whether the source supports events. * Search index must reflect changes within seconds → event-driven (webhooks fire immediately on publish). * Product page combines CMS content with live pricing → API-mediated (prices change independently, no copying). * 10,000 products need loading from a PIM → batch sync (bulk data, tolerance for latency). * Walk through the decision matrix on screen. Latency needs, data volume, coupling tolerance. * Call out the error handling differences: dead-letter queues for events, Promise.allSettled for runtime composition, checkpoint-based resumption for batch jobs. * Design webhook handlers to be idempotent — processing the same event twice must produce the same result. ### 5\. Contentstack Launch * Launch is Contentstack's built-in hosting platform: Git-based deployments, CDN distribution, content-triggered rebuilds, all from the CMS dashboard. * Git-connected: push to a branch, Launch builds and deploys. Supports Next.js, Nuxt, Astro, Gatsby, static generators, and SPAs. * Environment mapping: staging branch deploys to staging, main branch deploys to production. Each deployment uses the delivery token scoped to its Contentstack environment. * Auto-deploy on content publish: when an editor publishes, Launch rebuilds the associated deployment. This is valuable for SSG sites but redundant for SSR apps that fetch content on every request. * Environment variables with secrets support — tokens are encrypted, not visible after saving. * Preview URLs: editors get a .contentstacklaunch.com subdomain to verify before attaching a custom domain. ### 6\. Deployment flow demo * Walk through the end-to-end flow: editor publishes content → Contentstack detects mapped Launch deployment → Launch queues a build from the configured branch → build fetches latest content from Delivery API → new build deploys to CDN. * Show the two-environment setup: staging and production with different branches, different tokens, different custom domains. * Explain that Launch auto-injects Contentstack credentials as environment variables, reducing manual credential management. * Mention custom domains with automatic SSL provisioning via Let's Encrypt. ### 7\. Automate and Personalize * Automate is a visual flow builder for connecting Contentstack with external services without writing custom code. Triggers, conditions, actions, loops — all configured visually. * Distinguish from Automation Hub: Automation Hub handles internal CMS actions (notify editor on workflow change). Automate handles cross-system orchestration (Jira + Slack + Salesforce in one flow). * Distinguish from raw webhooks: webhooks are point-to-point and require you to build error handling, retry logic, and data transformation. Automate provides these out of the box with pre-built connectors. * Personalize: editors create content variants within a single entry (enterprise banner, free-tier banner, anonymous banner). Audience rules are defined in Personalize. The SDK resolves the correct variant at runtime. * The frontend renders whatever content Personalize resolves — no if (user.plan === 'enterprise') logic in your code. Audience rules are externalized so marketing can adjust targeting without code deployments. * Default variant serves as fallback when no audience rule matches. ### 8\. AI-assisted workflows * AI-generated content follows the same schema, workflows, and API contracts as human-written content. Your frontend needs zero special handling. * Built-in features: Brand Kit for voice/tone consistency, AI-assisted content generation within the editor, AI-powered content suggestions. * Custom integrations: use webhooks and the CMA to build pipelines — auto-generate summaries on entry creation, auto-tag with taxonomy terms, generate image alt text. * The AI content pipeline: creation (AI draft) → human review → enrichment (AI tagging, summarizing) → human approval → publish → delivery. * Every AI pipeline should terminate at a human review step before content reaches the Delivery API. AI assists editors; it does not replace editorial judgment. * Trigger AI processing at meaningful lifecycle points (entry creation, workflow stage changes), not on every field save — otherwise you burn through API costs. ### 9\. The developer role in AI-enabled operations * AI changes where you spend time, not whether you are needed. Content modeling, frontend dev, integration architecture — these remain your core responsibilities. * New responsibilities: building AI processing pipelines, evaluating AI providers (quality, latency, cost, data residency), implementing output validation, building feedback loops. * Guardrails: validate AI output before writing it back to Contentstack. Check format, length, allowed values. AI output is probabilistic, not deterministic. * Design content models with separate fields for AI suggestions and human-authored content so editors can compare and choose. Do not silently overwrite editor fields. * Build cost monitoring and acceptance tracking from the start. Without measurement, you cannot tell if AI integrations deliver value. * Security: sending content to external AI services means content leaves your infrastructure. Filter sensitive content types, check provider data policies, respect data residency requirements. ### 10\. Where the platform is heading + series wrap-up * Composable DXP means each system does what it does best. The CMS owns content. Commerce owns transactions. Search owns indexing. AI owns enrichment. The frontend composes them all. * MACH architecture (Microservices, API-first, Cloud-native, Headless) is the underlying philosophy. Contentstack fits naturally because it is API-first and headless by design. * Connect back to the full journey: Video 1 started with what Contentstack is and how headless CMS works. We progressed through content modeling, environments, the SDK and Delivery API, Live Preview, workflows, extensions, webhooks, and now the full composable picture. * The certification validates that you can design content models, build frontends, integrate external systems, deploy and host, and make architectural decisions about where data lives. * Close with: "You now have the toolkit to build production-grade content architectures. The rest is building." ## Screen: What to Show Outline item What to show on screen 1\. CMS as system of record Diagram: Contentstack at center with arrows to Commerce, Search, Analytics, Auth as separate boxes. Show the decision framework table from lesson content. 2\. Draw the boundary Split-screen diagram: left side "In Contentstack" (marketing pages, navigation, banners), right side "In Shopify/ERP" (pricing, inventory, orders). Show a JSON snippet of a product entry with shopify\_handle field. 3\. Integration patterns Architecture diagram showing three lanes: webhooks (event arrow from CMS to search index), API-mediated (frontend pulling from CMS + commerce + reviews), batch sync (cron job arrow from PIM to CMS). 4\. Decision framework Show the decision matrix table on screen: requirement → pattern → why. Walk through each row. 5\. Contentstack Launch Contentstack dashboard: Launch section. Show the deployment creation flow — connect repo, pick branch, set env vars. Show a live deployment URL. 6\. Deployment flow Diagram: editor publishes → Launch rebuilds → CDN serves. Show the two-environment table (staging vs production branches, tokens, domains). If time allows, trigger an actual content publish and show the build kicking off. 7\. Automate and Personalize Automate: show the visual flow builder with a trigger → condition → action chain. Personalize: show an entry with multiple variants in the editor, then show the SDK code that resolves the variant. 8\. AI-assisted workflows Show the AI content pipeline diagram (creation → review → enrichment → approval → publish → delivery). Show a code snippet of a webhook handler that calls an AI service and writes back via the CMA. 9\. Developer role in AI Show the AI guardrails code: tag validation function, cost tracking snippet. Show a content model with parallel fields (human-authored seo\_title vs AI-suggested suggested\_seo\_title). 10\. Platform direction + wrap-up Full composable architecture diagram with all pieces labeled. Then a recap slide connecting all 13 videos in the series — a visual journey map. ## Veda Scenario Thread Veda has been the throughline for the entire series. In this closing video, bring her story full circle: * **System of record:** Veda's travel platform uses Contentstack for destination descriptions, travel guides, and campaign content. Amadeus owns tour pricing and availability. A reviews platform owns user-generated ratings. The boundaries are clear because Veda drew them early. * **Integration patterns:** Veda uses all three patterns simultaneously — webhooks to update Algolia when destinations are published, API-mediated composition to show live tour prices alongside editorial content, and a nightly batch sync to import new photography from the DAM into Contentstack. * **Launch:** Veda deploys her Next.js frontend on Contentstack Launch with staging and production environments. When an editor publishes a new destination to staging, Launch rebuilds automatically and the team reviews at staging.veda-travel.com. * **Automate:** When a destination entry is approved, an Automate flow creates a Jira ticket for the partnerships team, posts to the #new-destinations Slack channel, and updates a Salesforce record — all without custom code. * **Personalize:** Veda's homepage shows different hero banners: returning visitors see personalized destination recommendations, first-time visitors see a general brand story, and visitors from partner referrals see co-branded messaging. The frontend code is identical for all visitors. * **AI workflows:** Veda's content team uses AI to draft destination summaries and auto-generate SEO metadata. A webhook triggers AI enrichment when entries reach the "Ready for Review" stage. Editors review AI suggestions alongside their own content before publishing. * **Wrap-up:** Veda started the series learning what Contentstack is. Now she is architecting a composable platform where the CMS is one piece of a larger system. That is the developer journey this certification represents. ## Transitions 1 → 2: "Now that we know Contentstack owns content and only content, let us draw the exact boundary for a real project." 2 → 3: "With boundaries drawn, the question becomes: how do these systems actually talk to each other?" 3 → 4: "Three patterns, three sets of trade-offs — so how do you pick the right one for a given integration point?" 4 → 5: "Once your content is integrated and your frontend is built, you need somewhere to host and deploy it." 5 → 6: "Let us walk through what this deployment flow actually looks like end to end." 6 → 7: "Beyond hosting, Contentstack gives you two more tools that extend the platform: Automate for workflow orchestration and Personalize for audience targeting." 7 → 8: "The newest layer in this stack is AI — and it plugs into the same editorial workflow we have been building throughout this series." 8 → 9: "AI changes the workflow, but it does not change your job title. Let us talk about what the developer actually owns in an AI-enabled CMS." 9 → 10: "We have covered the full composable picture. Let us zoom out one last time and put it all together." **Series closing wrap-up:** "This is where the series ends — but it is also where your work begins. Over thirteen videos, we went from understanding what a headless CMS is, to modeling content, to building frontends with the SDK, to Live Preview, workflows, extensions, webhooks, and now the full composable architecture. You have seen how Contentstack fits into a broader system, how to integrate it with commerce, search, AI, and deployment platforms, and how to make the architectural decisions that separate a working implementation from a well-designed one. The certification exam tests whether you can apply all of this. You are ready. Go build something." ## Common Mistakes to Call Out 1. **Storing pricing or inventory in the CMS.** Prices change with flash sales, regional rules, and dynamic algorithms. Inventory changes with every purchase. Neither follows an editorial workflow. The moment an editor publishes, the data is stale. Keep transactional data in the commerce platform and fetch it at render time. 2. **Using the CMS as a configuration store.** Storing API endpoints, feature flags, or redirect rules as Contentstack entries clutters the editorial interface with non-content data. Editors see content types they should not touch. Use environment variables or dedicated configuration services. 3. **Polling for changes instead of using webhooks.** A cron job that checks every 5 minutes whether content changed wastes resources and still has latency. Webhooks fire immediately on publish — use event-driven integration when you need near-real-time reactions. 4. **Copying external data into Contentstack instead of composing at runtime.** Syncing product prices into CMS fields every hour creates staleness, a single point of failure (the sync job), and forces editors to see data they should not manage. Use API-mediated composition at render time. 5. **Ignoring error handling in webhook endpoints.** A handler that returns 200 without checking downstream success silently loses events. If Algolia or Slack is down, the event is acknowledged and gone forever. Build idempotent handlers with dead-letter queues. 6. **Enabling auto-deploy for SSR applications.** If your app uses getServerSideProps exclusively, every content publish triggers a full rebuild that accomplishes nothing — SSR already fetches fresh content on each request. Auto-deploy is for static generation only. 7. **Using the same delivery token for staging and production Launch deployments.** Both deployments end up fetching from the same environment, so staging never shows draft or staged content. Each deployment must use the token scoped to its corresponding Contentstack environment. 8. **Hardcoding personalization logic in the frontend.** Writing if (user.plan === 'enterprise') scatters targeting rules across the codebase and requires code deployments to change them. Use Personalize to externalize audience rules so marketing can adjust targeting independently. 9. **Publishing AI-generated content without human review.** Bypassing workflow stages removes the editorial safety net and risks putting hallucinated, inaccurate, or off-brand content live. Every AI pipeline should terminate at a human review step. 10. **Treating AI integration as only a prompt engineering problem.** Neglecting error handling, output validation, cost monitoring, and feedback loops leads to pipelines that work in testing but fail unpredictably in production. AI integration is systems engineering. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 13 — Contentstack in a Composable DXP** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 15 — Video Production Plan : Overview #### Lesson text # Video Production Plan This curriculum spans 8 courses, 17 modules, and 62 lessons. Recording one video per lesson would be unsustainable. Instead, this plan bundles lessons into 13 high-value videos that cover the full certification path. ## Strategy * Bundle related lessons into cohesive narratives * Prioritize topics that are hardest to learn from text alone (architecture, implementation, visual features) * Use the Veda jewelry scenario as the consistent thread throughout * Estimated total runtime: ~4-5 hours * If time is tight, the 6 critical videos alone cover the core certification path in ~2 hours ## Priority Tiers Priority Videos Est. Runtime Description Critical 6 ~2-2.5 hours Record first. Hardest to learn from text, highest visual value. Core 5 ~1.5-2 hours Completes full curriculum coverage. Polish 2 ~30-40 min Conceptual and forward-looking. Can ship as text-only if needed. Total 13 ~4-5 hours ## Suggested Recording Order Record impact-first, not sequentially. The critical videos cover the concepts that are hardest to learn from text and that developers get wrong most often. ### Phase 1: Critical 1. [Video 3 — Structured Content and API Contracts](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/03-structured-content-and-api-contracts) 2. [Video 5 — API Architecture, Authentication, and Query Surface Choice](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/05-api-architecture-authentication-query-surface) 3. [Video 6 — Fetching and Rendering Content with the SDK](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/06-fetching-and-rendering-content) 4. [Video 8 — Live Preview Architecture and Preview Routing](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/08-live-preview-architecture-and-routing) 5. [Video 9 — Visual Builder, Releases, and Future-State Preview](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/09-visual-builder-releases-future-state) 6. [Video 11 — When To Customize: Configuration vs Apps vs Webhooks](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/11-when-to-customize) ### Phase 2: Core 1. [Video 7 — Performance, Images, Environments, and CLI Migrations](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/07-performance-images-environments-cli) 2. [Video 10 — Workflow, Automation Hub, and Branch Strategy](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/10-workflow-automation-branch-strategy) 3. [Video 2 — Headless Foundations and Designing for Editors](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/02-headless-foundations-and-designing-for-editors) 4. [Video 4 — Composition, Query Performance, and Modeling in Practice](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/04-composition-query-performance-modeling) 5. [Video 1 — Start Here: Certification Roadmap and First API Call](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/01-start-here-certification-roadmap) ### Phase 3: Polish 1. [Video 12 — Maintainability, Governance, and Long-Term Ownership](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/12-maintainability-governance-ownership) 2. [Video 13 — Contentstack in a Composable DXP](https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/13-contentstack-in-composable-dxp) ## Expansion Candidates If learner feedback shows specific modules need more depth, these are the best candidates for splitting into 2-part videos: * **Module 3.2 (Fetching and Rendering):** split into fetch/query basics + performance/images/frontend patterns * **Module 4.1 (Live Preview and Visual Builder):** split into preview architecture + Visual Builder implementation * **Module 6.1 (Extension Architecture):** split into decision framework/marketplace + custom apps/webhooks ## Recording Tips * **Videos 1-7 (Courses 0-3):** Heavy on screencasts — Contentstack UI, code editor, and terminal side by side * **Videos 8-9 (Course 4):** Most visually compelling — show Live Preview and Visual Builder in full editorial flow * **Video 10 (Course 5):** Mix of UI walkthroughs and architecture diagrams * **Videos 11-12 (Course 6):** Developer Hub demos + conceptual slides * **Video 13 (Course 7):** Architecture diagrams with occasional platform demos * **All videos:** Use the Veda jewelry scenario as the consistent thread * **All videos:** End each video with a clear transition to what comes next in the curriculum #### Key takeaways - Connect **Video Production Plan : Overview** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 16 — Video Production Plan : Video 1 — Start Here - Certification Roadmap and First API Call #### Lesson text # Video 1 — Start Here: Certification Roadmap and First API Call Attribute Details Course 0 (Orientation) Covers Lessons 0.1.1, 0.1.2, 0.1.3 Priority Core Length 10-15 min Format Screencast (Contentstack UI + terminal) Status Not started ## Why This Video Matters Gives learners an early win and reduces drop-off at the start of the certification. This is the first thing people see — it needs to be welcoming and confidence-building. ## Outline 1. Who this certification is for and what the learner is expected to already know 2. How the curriculum is structured across 7 courses 3. Quick tour of the documentation ecosystem: developer docs, API references, SDKs (JS, Python, Java, .NET, Ruby, Swift, Dart, Flutter) 4. Regional API base URLs, Postman collections, GitHub repos 5. Open the Contentstack dashboard: show a stack, a content type, and an entry 6. Make a live Content Delivery API call with curl — walk through the request and the JSON response 7. Repeat the same query with the JavaScript SDK to show the abstraction layer 8. How to study the rest of the curriculum efficiently ## Key Lines "This certification is easier if you think of it as one continuous build journey, not a set of disconnected lessons." "You do not need to memorize every API detail. You need to know where to find the right reference quickly." "You just fetched your first entry. Everything in this certification builds on this." ## Detailed Talking Points ### 1\. Who this certification is for and what the learner is expected to already know * "This certification is for developers who build on top of Contentstack — frontend devs consuming delivery APIs, fullstack devs wiring up preview and webhooks, backend devs integrating into platform architectures." * Explain that no prior Contentstack experience is needed, but they should be comfortable with HTML/CSS/JS, REST APIs, JSON, and have used fetch or axios before. * Mention the free developer plan — they can sign up and get a stack before starting. * Call out what this certification does NOT cover: pricing, sales/marketing features (Personalize, A/B testing), admin tasks (SSO/SAML), or framework-specific tutorials. "This is about Contentstack concepts that apply no matter what framework you use." ### 2\. How the curriculum is structured across 7 courses * Walk through each course in one sentence: * Course 1: Foundations — mental model for headless, the 5 building blocks * Course 2: Content Modeling — designing schemas that serve editors AND APIs * Course 3: APIs and Tooling — Delivery API, Management API, REST vs GraphQL, SDK, CLI * Course 4: Preview and Visual Builder — Live Preview, Visual Builder, releases * Course 5: Workflows and Branches — content lifecycle, automation, branching * Course 6: Extensions — when to customize, apps, webhooks * Course 7: Integrations — composable DXP, Launch, Automate, Personalize * Emphasize: "Course 1 is mandatory first. After that, you can jump to whatever is most relevant to your current work." * Mention the lesson structure: every lesson has a TL;DR, core content, practice activity, common mistakes, and self-check questions. "The self-checks test application, not recall. If you can't answer them, re-read before moving on." ### 3\. Quick tour of the documentation ecosystem * Show the developer docs landing page at [contentstack.com/docs/developers/](/docs/developers/) — "Bookmark this. You'll come back to it constantly." * Three API surfaces: Content Delivery API (REST), Content Management API (REST), GraphQL Content Delivery API. Briefly explain each in one sentence. * "The Delivery API is what your frontend calls in production. The Management API is for automation, migrations, and admin scripts. GraphQL lets you request exactly the fields you need." * Mention the SDKs: JavaScript/Node.js (most common), Python, Java, .NET, Ruby, Swift, Dart/Flutter. "You don't need to learn them all. Pick the one for your stack." * Point out the SDK docs vs raw API reference distinction: "When an SDK method behaves unexpectedly, check the raw API reference or the SDK source on GitHub. SDK docs sometimes lag behind." ### 4\. Regional API base URLs, Postman collections, GitHub repos * Show the region table: NA (cdn.contentstack.io), EU (eu-cdn.contentstack.com), Azure NA (azure-na-cdn.contentstack.com), Azure EU (azure-eu-cdn.contentstack.com), GCP NA (gcp-na-cdn.contentstack.com). * "Using the wrong base URL is the number one cause of 'stack not found' errors. It's not an auth problem — it's a region mismatch." * Show where to find your stack's region in the dashboard under stack settings. * Mention Postman collections — "Import the collection, set up an environment with your api\_key, access\_token, and base\_url, and you can explore every endpoint without writing code." * Point to [github.com/contentstack](https://github.com/contentstack) — SDKs, sample apps (Next.js, Gatsby, Nuxt, Angular), CLI tools. * Mention npm install -g @contentstack/cli — "We'll use this heavily in Course 3, but know it exists." ### 5\. Open the Contentstack dashboard: show a stack, a content type, and an entry * Open the Veda stack in the dashboard. Point out the stack API key in settings. * Navigate to Content Types. Open the product content type. "This is both a schema and an editor interface. Every field UID you see here becomes a JSON key in the API response." * Point out the field UIDs vs display names — short\_description is the API key, "Short Description" is what editors see. * Open a published entry (e.g., a Veda product). Show the title, locale, reference fields, and asset fields. * Note the environment and the delivery token scoped to it. ### 6\. Make a live Content Delivery API call with curl * Switch to terminal. Run: curl -s "https://cdn.contentstack.io/v3/content\_types/product/entries?environment=development" \\ -H "api\_key: YOUR\_KEY" \\ -H "access\_token: YOUR\_TOKEN" | jq * Walk through the response: the entries array, field UIDs matching the schema, system fields like uid, locale, timestamps. * "Look at one entry. Which fields would a listing page need? Which fields would a detail page need? Which fields stay internal to editors? This is the core shift — you're not building around pages the CMS owns. You're consuming structured JSON." * If it fails: "Check region first, then environment, then token scope. Most first-time failures aren't auth issues — they're context mismatches." ### 7\. Repeat the same query with the JavaScript SDK * Show the SDK initialization code: import Contentstack from "@contentstack/delivery-sdk"; const stack = Contentstack.stack({ apiKey: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY!, deliveryToken: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_DELIVERY\_TOKEN!, environment: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_ENVIRONMENT!, region: Contentstack.Region.US, }); const result = await stack.contentType("product").entry().query().find(); console.log(result.entries\[0\]); * "Same content, same response shape, but now through a developer-friendly library. You don't need to master this yet. The point is seeing that you have two ways in: raw HTTP and SDK." ### 8\. How to study the rest of the curriculum efficiently * "Work through Course 1 first. Every later course assumes you understand its vocabulary." * "Keep a stack open while you study. Reading about content types is useful; creating one and fetching from it through the API is where it sticks." * "Give the self-check questions real effort. If you can't answer them, the next lesson will be harder." * "This curriculum is also a reference. When you hit a real-world content modeling decision or API challenge, come back to the relevant lesson." ## Screen: What to Show 1. Curriculum site — show the course catalog / home page briefly 2. Developer docs — [contentstack.com/docs/developers/](/docs/developers/) landing page, scroll through the navigation 3. API reference — open the Content Delivery API reference, show an endpoint page briefly 4. Region table — either the docs page or a slide showing the 5 regions and their base URLs 5. Contentstack dashboard — navigate to: Settings → API keys (show stack API key and region), Content Types → open product, Entries → open a Veda product entry 6. Terminal — run the curl command, pipe to jq, show the JSON response 7. Code editor — show the SDK initialization code, run it, show console output 8. Postman (optional) — quickly show a pre-configured Postman collection request ## Veda Scenario Thread Introduce Veda here for the first time: "Veda is an upscale all-gender jewelry line — four distinct sets inspired by early 2000s pop culture, reinterpreted with modern luxury. Silver, gold, diamonds. This isn't just an example — it's the storefront you'll return to across every course. The same products, categories, and pages will anchor content modeling, API calls, preview, workflows, and integrations." Use a Veda product entry for the curl demo and SDK demo so learners connect to it immediately. ## Transitions * Curriculum overview → docs tour: "Before we start building, let me show you where to find answers when you need them." * Docs tour → regional URLs: "One thing that trips people up immediately — your API base URL depends on your region." * Regional URLs → dashboard walkthrough: "Let's look at the actual stack we'll be working with." * Dashboard → curl call: "Now let's prove this works. I'm going to fetch this entry through the API." * Curl → SDK: "Same query, but this time through the JavaScript SDK." * SDK → study tips: "You just fetched your first entry. Here's how to make the rest of this certification as efficient as possible." * Closing → Video 2: "Next, we'll zoom out and build the mental model for headless architecture — what Contentstack is responsible for, what you're responsible for, and why that distinction matters for every decision you'll make." ## Common Mistakes to Call Out 1. Treating the dashboard as the whole product — "If you only click around the UI and never inspect the API response, Contentstack still feels like a form builder. It's not. It's a structured content platform. The API response is the product." 2. Using the wrong region or environment — "Many first-time delivery failures aren't authentication failures. They're context mismatches: wrong base URL, wrong environment name, or content that was never published to that environment." 3. Waiting until Course 3 to touch the APIs — "Don't do this. One successful request now pays off for the rest of the path. The certification gets easier when you connect concepts to a real response early." ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 1 — Start Here - Certification Roadmap and First API Call** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 17 — Video Production Plan : Video 2 — Headless Foundations and Designing for Editors #### Lesson text # Video 2 — Headless Foundations and Designing for Editors Attribute Details Course 1 (Foundations) Covers Lessons 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.2.1, 1.2.2, 1.2.3 Priority Core Length 15-20 min Format Slides/diagrams + Contentstack UI walkthrough + good vs bad content type comparison Status Not started ## Why This Video Matters Establishes the mental model that everything else depends on. If learners don't understand headless boundaries and the editor-developer relationship, every later topic is harder. ## Outline 1. What headless really means: the CMS does not own rendering — developers own framework, hosting, and rendering strategy 2. Compare monolithic (WordPress/Drupal renders pages) vs headless (API-first, frontend renders) 3. Gains: framework freedom, deployment flexibility, multi-channel delivery, independent scaling, reduced security surface 4. Losses: no built-in page rendering, no URL routing, preview requires implementation, content-to-page mapping is your job 5. The 5 building blocks: Stacks, Content Types, Entries, Assets, Environments — walk through each in the UI 6. Draw the boundary: what Contentstack IS vs IS NOT 7. Content types as dual-purpose: API contract AND editor interface 8. Field UIDs become API keys; Display Names become editor labels — show this mapping live 9. Constraints vs flexibility: over-constraining causes workarounds; under-constraining pushes quality control to frontend 10. Collaboration patterns that work vs anti-patterns ## Key Lines "Headless is not just a tooling choice. It is a responsibility shift." "A content type is not only a schema. It is also an editor interface." "Your content model is a product. Your editors are your users." ## Detailed Talking Points ### 1\. What headless really means * Start with the misconception: "headless" is the most misused word in CMS marketing. Vendors slap it on everything. What it actually means is one architectural fact: the CMS does not own the rendering layer. * The metaphor: the "head" in a traditional CMS is the presentation layer — templates, routing, HTML output. Remove that, and you have a headless CMS. * Ownership, not tooling: headless is not a framework decision. You could build a headless frontend with jQuery and server-rendered PHP. The CMS is headless because it does not render — your framework choice is a separate decision. * In Contentstack specifically: you define content types, create entries, and the platform serves them via REST and GraphQL APIs. It does not generate a single HTML page. No template engine, no routing layer, no SSR pipeline inside the platform. * The Veda angle: when an editor publishes the "Matrix Link Bracelet" product entry, Contentstack makes that JSON available via API. Whether it becomes a web page, a mobile screen, or a kiosk display depends entirely on what you build. * The responsibility shift: everything downstream of the API — framework, hosting, rendering strategy, URL structure, page composition — is yours to build and maintain. ### 2\. Monolithic vs headless comparison * WordPress example: create a page, hit Publish, and the CMS writes to MySQL, selects a PHP template from your active theme, executes it, and returns rendered HTML. The CMS owns every step from storage to browser output. * Drupal follows the same pattern: Twig templates, render arrays, theme layer — CMS controls the full response lifecycle. * Contentstack: editor publishes an entry, content lands on the delivery API. Full stop. Your Next.js app, your Nuxt site, your Astro project makes an API call, gets JSON, renders it however you decided. * Key point: this is an architectural distinction, not a quality judgment. Calling something headless does not make it better. It means the rendering responsibility moved. * Tie it together: the separation means CMS and frontend have independent deployment lifecycles, separate hosting, separate tech stacks. Content publishing and code deployment are decoupled. ### 3\. What you gain * Framework freedom: React, Vue, Svelte, Astro, Qwik — all valid because the CMS only provides content via API. You can also switch frameworks without migrating the CMS — build a new frontend, point it at the same APIs, retire the old one. * Deployment flexibility: your frontend is an independent app. Deploy it to Vercel, Netlify, Cloudflare Pages, AWS, your own infrastructure. Optimize for your traffic patterns and cost constraints. * Multi-channel delivery: one Contentstack stack can serve a website, mobile app, digital kiosk, voice assistant. For Veda, the same product content could power the web storefront and an in-store display. * Independent scaling: a viral product launch puts load on your frontend and the CDN-backed delivery API, not on the content management system. Editors keep working uninterrupted. * Security surface reduction: end users never touch the CMS directly. No WordPress-style vulnerabilities where the same app that serves pages also processes admin requests. * Separation of concerns: content team works in the CMS, dev team works on the frontend. The API contract (content model) is the boundary between them. ### 4\. What you give up * No built-in page rendering: creating a content type and entries gives you structured data behind an API. To see a web page, you build a frontend. This includes layout, component mapping, responsive design, accessibility, performance optimization. * No URL routing: WordPress auto-generates /blog/my-post-title/. In headless, you design the URL structure, implement routing in your framework, and handle redirects, canonical URLs, sitemap generation yourself. This is commonly underestimated. * Preview requires implementation: in WordPress, "Preview" just works because the CMS renders the page. In headless, you build preview mode — configure preview tokens, set up preview-aware routing, integrate the Live Preview SDK. Preview is a feature you build, not a feature you get. * Content-to-page mapping is your problem: a homepage might pull from Hero Banner, Featured Products, Latest Articles, and Promotional Banner content types. The composition logic, query strategy, and rendering orchestration are all yours. * Editor experience depends on your investment: if you do not implement Live Preview, editors cannot see changes in context. If you skip Visual Builder, editors cannot edit on-page. Two identical Contentstack projects can have radically different editor experiences based purely on developer effort. ### 5\. The 5 building blocks * **Stacks:** the top-level container. Everything lives inside a stack — content types, entries, assets, environments, locales, branches, tokens, workflows, webhooks. Think of it as a project boundary. For Veda, one stack named veda-revival-web holds everything for the storefront. * **Content Types:** schemas that define the structure of content. Declare fields, data types, validation rules. A content type defines the shape of the JSON the API returns. For Veda: Product (title, short\_description, price, media, product\_line reference), Product Line, Category, Page with Modular Blocks. * **Entries:** instances of content types. The data. When an editor clicks "Create Entry" and selects a content type, they get a form generated from the schema. Entries exist independently of any page — a Product entry is structured data until your frontend fetches and renders it. * **Assets:** files in Contentstack's repository — images, PDFs, videos. Each gets a CDN-backed URL. Image transformation pipeline built in: append ?width=400&format=webp to resize and convert on the fly. No separate image processing service needed. * **Environments:** deployment targets. development, staging, production. Each has its own delivery token. Publish an entry to staging for review without it appearing on production. This is how you prevent draft content from leaking to the live site. * The fundamental loop: model content types, create entries, publish to environments, deliver via API. Every other feature extends this loop. ### 6\. Drawing the CMS boundary * The boundary principle: Contentstack is the system of record for content. Content means structured editorial material — what editors create, review, approve, and publish through editorial workflows. * What it IS: content storage with versioning, editorial workflows, multi-environment publishing, API delivery (REST + GraphQL + CMA), asset hosting with CDN and image transforms, webhooks for event-driven architecture, Live Preview and Visual Builder infrastructure, content branches for safe schema evolution. * What it IS NOT: a web host, a server-side application runtime, an end-user authentication system, an e-commerce transaction processor, a general-purpose database, a job scheduler, a URL router. * Concrete examples to drive the point home: Contentstack can store product descriptions for Veda, but it does not process orders — that is Shopify or commercetools. It can store a URL slug in a field, but it does not enforce that as a route — your frontend does that. It manages CMS user access, but it has no concept of your website's visitors. * Why this matters: clear boundaries keep the CMS performant and make team responsibilities unambiguous. A system that tries to do everything does nothing well. ### 7\. Content types as dual-purpose * This is the single most important concept for developers working in a headless CMS: a content type is simultaneously an API contract AND an editor interface. * When you open the Content Type Builder and add fields, every field you drag onto the canvas appears as an input element in the entry editor. You are writing a schema and designing a UI at the same time. * The field's Display Name becomes the label editors read. The field's help text becomes the guidance they rely on. The field's position determines the order editors work through. * For Veda: a Product content type is both the JSON shape your Next.js app consumes and the form an editor fills out 50 times a day. * Consequence: if you name fields for the API and ignore the editor, you get a technically clean schema with a terrible editing experience. If you design only for editors without thinking about the API, you get messy JSON that is painful to consume. ### 8\. Field UIDs become API keys * Every field has two names: the UID (machine-readable, used in API responses — becomes a JSON key) and the Display Name (human-readable, shown to editors). * Developers focus on UIDs because that is what appears in code. Editors never see UIDs — they only see Display Names. * Show this mapping live: a field with UID short\_description and Display Name "Marketing Tagline (max 120 chars)" — the editor sees the friendly label, the API returns the clean key. * Good Display Names communicate purpose, not just data type. Not "Image" but "Hero Image (1920x1080)." Not "URL" but "External Link (full URL including https)." Not "Body" but "Product Description (long-form content)." * Help text is inline documentation editors actually read. It answers: What goes here? Why does it matter? What are the constraints? Example: "Write a 150-160 character summary of this page. This appears in Google search results below the page title." * Field order matters: editors work top to bottom. Put identity fields first (title, slug), then primary content, then supporting content (images, references), then metadata (SEO) last. ### 9\. Constraints vs flexibility * Over-constraining forces workarounds: if every field is mandatory, editors upload placeholder images, enter dummy text, misuse fields. The data becomes unreliable not because editors are careless but because the system gave them no legitimate path. * Veda scenario: a Product content type with a mandatory "Featured Image" field. The team wants to publish a placeholder product without an image yet. They upload a blank white square. The frontend now displays a meaningless image. * Under-constraining pushes quality control to the frontend: no mandatory fields means inconsistent content. One author adds SEO descriptions, another skips them. One uploads 1920x1080 hero images, another uploads phone screenshots. The developer writes defensive code for every variation — expensive to build, hard to maintain. * The guideline: make a field mandatory only if the frontend breaks without it. Use help text as a behavioral guardrail for everything else. * Modular Blocks as the sweet spot: define a set of named blocks (Hero, Rich Text, Image Gallery, CTA, Video Embed), each with their own fields. Editors compose pages by selecting and ordering blocks. They get creative freedom within developer-defined structure. The API response is a typed array — no surprises. * Start loose, tighten based on data: at launch, keep constraints minimal. After three months, you have real usage data. See which fields are always filled (candidates for mandatory), which follow patterns (candidates for validation), which are never used (candidates for removal). ### 10\. Collaboration patterns vs anti-patterns * **Pattern: Content model co-design** — 30-minute session per content type with one or two editors. Open the Content Type Builder, walk through each field together. Developers learn editors call "Summary" "Teaser Text." Editors learn the Hero Image needs 16:9 aspect ratio. Both discover the Author reference needs to allow multiple authors. * **Pattern: Staged rollout** — do not deploy a new content type directly to production. Use dev environment first, invite editors to create test entries with real content (not lorem ipsum), gather feedback, iterate, then deploy to production. Adds a few days but prevents weeks of rework. * **Pattern: Documentation as conversation** — put documentation in the content type itself. Help text on every field, content type description explaining when to use it. External wikis decay. In-context help travels with the content type. * **Pattern: Preview-driven development** — implement Live Preview early, not as post-launch polish. When editors see their changes rendered in real time, they need less guidance about constraints. An editor who uploads a low-res image and sees it blurry in preview understands the requirement viscerally. * **Anti-pattern: "Dev builds, editor adapts"** — developer designs content types in isolation, editor sees them for the first time when entering content. Result: field names do not match editor vocabulary, order is wrong, help text is missing, constraints are either too tight or nonexistent. Two hours to design, two weeks to stabilize. * **Anti-pattern: "Editor-designed content types"** — editors specify exactly what fields they want, developers implement without pushback. Editors think in pages and layouts — they request "Left Column Text" and "Right Column Text" which encodes layout into the content model. When design changes, field names become misleading. * **Anti-pattern: "Change on request"** — every editor request becomes a field addition. Over months, content types accumulate 35 fields, most empty in 90% of entries. This is field sprawl — the content modeling equivalent of tech debt. ## Screen: What to Show ### 1\. What headless really means * Open a simple diagram (prepared slide) showing: CMS box on the left labeled "Content Storage + API," arrow pointing right to multiple frontend boxes (web, mobile, kiosk). Contrast with a monolithic diagram where everything is one box. ### 2\. Monolithic vs headless comparison * Side-by-side slide: left side shows WordPress flow (Content -> PHP Template -> HTML -> Browser, all inside one box). Right side shows Contentstack flow (Content -> API -> \[gap\] -> Your Frontend -> Browser, with the gap highlighted as "your responsibility"). ### 3\. What you gain * Quick slide listing the six gains with icons. No need to linger — this is a verbal section. ### 4\. What you give up * Same format: slide listing the five losses. Highlight "Preview requires implementation" with a callout box — this surprises people the most. ### 5\. The 5 building blocks * Switch to the Contentstack UI. Open the Veda stack. * Show the stack dashboard — point out the left-hand navigation sections. * Click into Content Models and open the Product content type. Show the field list in the Content Type Builder. * Click into Entries and show the list of Product entries. Open the "Matrix Link Bracelet" entry to show the editor form generated from the content type. * Click into Assets and show the folder structure with Veda product photography. * Click into Settings > Environments and show the three environments (development, staging, production) with their base URLs. * Briefly show the relationship: "Content type defines the schema, entry is an instance, assets are referenced, published to an environment, delivered via API." ### 6\. Drawing the CMS boundary * Return to the slide deck. Show a two-column slide: "Contentstack Does" on the left (content storage, workflows, API delivery, asset CDN, webhooks, Live Preview infra, branches) and "Your Responsibility" on the right (hosting, rendering, routing, auth, e-commerce, scheduled jobs, URL management). Draw a clear vertical line between them. ### 7\. Content types as dual-purpose * Back in the Contentstack UI. Open the Product content type in the Content Type Builder. Point at the field list and say: "This is simultaneously the API contract and the editor interface." * Then open an entry of that content type side by side (or switch between tabs) to show how each field in the builder maps to an input element in the entry editor. ### 8\. Field UIDs become API keys * In the Content Type Builder, click on a field (e.g., the short\_description field on the Product content type). Show the UID field and the Display Name field side by side in the field settings panel. * Then open a browser tab with the Contentstack API Explorer or a raw JSON API response for a Product entry. Point at the JSON key that matches the UID. Show that the Display Name does not appear in the API — it is only for editors. * Scroll through the entry editor and point out help text on fields, showing how it appears directly below the label. ### 9\. Constraints vs flexibility * In the Content Type Builder, open the Product content type. Click on a field and show the "Mandatory" toggle and validation rules (min/max length, regex). * Create or show a comparison: a content type with every field marked mandatory vs one with sensible defaults. If possible, show a screenshot of the editor hitting a wall of red validation errors vs a clean save experience. * Open a Page content type that uses Modular Blocks. Show the block type definitions (Hero Block, Rich Text Block, CTA Block). Switch to an entry and show how editors add and reorder blocks — the compositional freedom within guardrails. ### 10\. Collaboration patterns vs anti-patterns * Show a slide with two columns: "Patterns That Work" (co-design, staged rollout, in-context docs, preview-driven dev) and "Anti-Patterns" (dev builds alone, editor-designed types, change on request). * Quick screenshare: open a content type and show the Description field (where you document when to use this content type). Show a field's help text as an example of documentation that lives in-context. * If Live Preview is configured on the Veda stack, show the Live Preview panel — editor changes a product title, preview updates in real time. This is the money shot for this section. ## Veda Scenario Thread * **Opening (building blocks):** introduce the Veda stack as the running example. "We are building the storefront for Veda: The Revival Collection — a luxury jewelry brand. Everything we talk about today, we will see in this stack." * **Stacks:** the Veda stack (veda-revival-web) is the project container. All product content, collection pages, and campaign assets live here. If Veda launches a mobile app later, it can consume from the same stack — multi-channel from a single content source. * **Content Types:** walk through Veda's Product content type (title, short\_description, price, media, product\_line reference, category reference), Product Line content type (Digital Dawn collection), and Page content type with Modular Blocks for the homepage. * **Entries:** show real Veda entries — "Matrix Link Bracelet" at $295 in the Digital Dawn product line. Show a Page entry for "The Revival Collection" homepage composed from modular blocks. * **Assets:** Veda product photography, collection hero images, brand logo — all managed in the asset repository with CDN delivery and image transforms. * **Environments:** Veda's three environments — development (where devs test rendering), staging (where editors preview before go-live), production (the live storefront). * **CMS boundary:** Veda sells jewelry, but Contentstack does not process orders. Product content lives in the CMS; transaction processing lives in the commerce platform. The URL /products/matrix-link-bracelet is defined by the frontend, not the CMS. * **Dual-purpose content type:** the Product content type is both the JSON shape the Veda Next.js app consumes and the form editors fill out when adding new jewelry pieces to the catalog. * **Constraints:** the Product title and price are mandatory (the frontend breaks without them). The promotional tagline is optional with help text. The featured image is strongly recommended via help text but not mandatory — because sometimes a product is listed before photography is ready. * **Collaboration:** when the Veda team designed the Product content type, they sat with the merchandising editor and walked through each field. The editor pointed out that "short\_description" should be labeled "Marketing Tagline (max 120 chars)" because that matches their content brief. That 30-minute session prevented weeks of confusion. ## Transitions 1. From intro to headless definition: "Before we touch any code or UI, we need to get one foundational concept right — what headless actually means, in terms of responsibility, not buzzwords." 2. **From headless definition to monolithic comparison:** "To make this concrete, let's compare what happens when you hit Publish in WordPress versus what happens in Contentstack." 3. **From comparison to gains:** "That separation sounds like you are losing features — and you are — but you are gaining something significant in return." 4. **From gains to losses:** "Now let's be honest about the other side of that trade, because pretending headless is universally better does not help anyone build real projects." 5. **From losses to building blocks:** "Alright, you understand the architecture and the tradeoffs. Let's get hands-on and look at the five building blocks you will work with every day." 6. **From building blocks to CMS boundary:** "Now that you have seen the pieces, let's draw a clear line around what Contentstack is responsible for and what is yours." 7. **From boundary to dual-purpose content types:** "This boundary leads directly to a concept that changes how you think about content modeling: your content type is not just a schema." 8. **From dual-purpose to field UIDs:** "Let's zoom in on the mechanics — how field UIDs map to API keys and Display Names map to editor labels." 9. **From field UIDs to constraints vs flexibility:** "Now that you see how fields shape both the API and the editor experience, the question becomes: how tightly do you control what editors can do?" 10. **From constraints to collaboration patterns:** "Getting the constraints right is not something you do alone — it requires working with the people who actually use the system every day." 11. **Closing transition to Video 3:** "You now have the mental model: headless architecture, the five building blocks, content types as dual-purpose contracts, and how to work with editors. In the next video, we go deep on the content modeling itself — field types, references, Modular Blocks, and the design patterns that separate a clean content model from a messy one." ## Common Mistakes to Call Out 1. **Equating "headless" with "better":** headless describes architecture, not quality. A poorly implemented headless site is worse than a well-maintained WordPress site. The architecture enables flexibility; it does not guarantee outcomes. 2. **Assuming the CMS handles routing or page generation:** developers from WordPress/Drupal expect the CMS to produce pages or manage URLs. In headless, the CMS produces structured content via APIs. Routing, URL generation, page composition, and HTML rendering are entirely the frontend's job. 3. **Treating headless as a framework decision:** choosing React or Next.js is not what makes a CMS headless. The CMS is headless because it does not own rendering. The framework is your choice; the architecture is the CMS's characteristic. 4. **Adopting headless without frontend development capacity:** the most expensive version of this mistake is an organization that chooses a headless CMS, then discovers every page change requires developer involvement because no one anticipated the frontend build cost. 5. **Underestimating preview and editorial tooling investment:** developers focus on the API and rendering pipeline. Editors need to see content in context. Treating Live Preview and Visual Builder as optional polish leads to editor frustration and slower content operations. 6. **Comparing CMS license cost instead of total cost of ownership:** frontend development, hosting infrastructure, preview tooling, deployment pipelines, and ongoing maintenance are all costs that exist in headless but are partially absorbed in traditional CMS setups. 7. **Confusing content types with pages:** a content type called "Page" defines fields, not a rendered page. Multiple entries from different content types compose a single page, and a single entry might appear on multiple pages. 8. **Using one environment for everything:** running dev, staging, and production through a single environment removes the ability to preview and validate content before it reaches end users — and risks leaking draft content to the live site. 9. **Storing non-content data in content types:** feature flags, app config, transactional records — these clutter the editorial interface and push the CMS beyond its design. Use environment variables or dedicated configuration services. 10. **Naming fields for the API instead of the editor:** using terse names like "desc" or "img\_alt" as Display Names forces editors to decode developer shorthand. Always write Display Names in plain language that describes what the editor should enter. 11. **Skipping help text entirely:** developers assume editors understand the content model. They do not. Every field without help text is a field where editors must guess or ask. 12. **Making every field mandatory on the first iteration:** developers who have not seen real content overestimate what is required. Start with only structurally essential fields as mandatory and tighten after observing real editorial usage. 13. **Treating content type design as a one-time task:** content types designed before editors start working almost always need revision. Plan for iteration and build a feedback loop into your project. 14. Relying on external documentation instead of in-context help text: a Confluence page with content type docs is better than nothing, but it decays within months. Put essential guidance inside the content type itself. 15. Skipping preview integration because it is "not a priority": Live Preview is the single most effective tool for reducing editor errors and support requests. Implementing it early saves more time than almost any other developer investment. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 2 — Headless Foundations and Designing for Editors** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 18 — Video Production Plan : Video 3 — Structured Content and API Contracts #### Lesson text # Video 3 — Structured Content and API Contracts Attribute Details Course 2 (Content Modeling), Module 2.1 Covers Lessons 2.1.1, 2.1.2, 2.1.3, 2.1.4 Priority Critical Length 18-25 min Format Screencast (Contentstack UI + code editor side-by-side) Status Not started ## Why This Video Matters This is one of the most important videos in the entire series. It shapes how learners think about content from the start. If the model is wrong, the frontend, editorial workflow, and APIs all become harder. ## Outline 1. The mindset shift: stop thinking in pages, start thinking in domain concepts 2. Three questions for every content type: Does the concept exist independently? Will it appear in multiple contexts? Would editors update it separately? 3. Veda example: Product, Product Line, Category, Page — four types connected by references instead of one giant page template 4. Content types as API contracts: every field UID becomes a JSON key in the response 5. Show a content type definition and the resulting API response side-by-side 6. Breaking changes: renaming or removing a field UID on published entries breaks frontends immediately. Adding fields is safe (null default) 7. TypeScript interfaces should mirror content type schemas 8. Global Fields: define a field group once, reuse across content types, changes propagate everywhere 9. When to use Global Fields (SEO metadata, addresses, CTAs used by 3+ types) vs when not to 10. JSON Rich Text Editor: structured document tree, not HTML string — show the raw JSON 11. Embedded entries/assets as reference nodes; rendering with @contentstack/utils 12. Custom RTE plugins: extending the editor toolbar via Developer Hub ## Key Lines "If the model is wrong, the frontend, editorial workflow, and APIs all become harder." "A content model is an agreement between the CMS and downstream consumers." "The question is not 'can we model this', but 'can we model this in a way that stays healthy over time'." ## Detailed Talking Points ### 1\. The mindset shift: stop thinking in pages, start thinking in domain concepts * Traditional CMS platforms organize content around pages — one URL, one template, one database row with everything bolted on. * That works until someone asks you to show the same product on a mobile app, a marketplace feed, or a store display. The page abstraction falls apart. * Structured content separates what the content is from where and how it appears. * Instead of a "Product Page" you model the domain concept "Product" — title, price, description, media. No layout, no template assumptions. * Authors think in entries, designers think in components, developers think in API consumers. Everyone stops coupling to a single page template. * The CMS becomes a content API, not a page factory. ### 2\. Three questions for every content type * Before you create a content type, run it through three questions. * First: does this concept exist independently? A product line like Digital Dawn exists whether or not it has products yet. That means it deserves its own content type, not a text field inside Product. * Second: will this content appear in more than one context? If categories show up on product pages, category landing pages, and navigation menus, they need to be their own type with references — not embedded text you copy-paste. * Third: would editors need to update this independently? If changing a product line description should not require opening every product, the product line must be a separate entry. * These three questions consistently push you toward smaller, focused content types connected by references. * If the answer is "no" to all three, it can stay as a field group or a group field inside the parent type. ### 3\. Veda example: Product, Product Line, Category, Page * Walk through the Veda jewelry catalog as a concrete migration from page-oriented to structured content. * In a page CMS, a single product page row holds title, description, price, images, product line name, category name, SEO metadata — everything in one record. * In Contentstack, decompose into four content types: Product (title, url, short\_description, description, price, media, product\_line reference, category reference), Product Line (title, url, description, image, products reference), Category (title, url, description, media), Page (title, url, components as modular blocks). * Product references Product Line and Category — the product line description exists in exactly one place. Change it once, every product reflects the update. * The mobile app fetches Product with include\[\]=product\_line and gets clean JSON. The marketplace feed requests only title, price, and media using field projection. No HTML parsing, no screen-scraping. * Show the multi-channel reuse table: Website gets full product with description and images. Mobile app gets product summary, price, media. Marketplace feed gets title, price, short description, first image. Email campaign gets title, short description, hero image, link. Partner API feed gets product data without branding. In-store display gets product images and QR code. * One content model, six channels, zero duplication. ### 4\. Content types as API contracts: every field UID becomes a JSON key * This is the big mental model shift for developers: a content type is not just a form for editors. It is simultaneously a JSON schema that your frontend codes against. * The moment you save a content type with a field UID of short\_description, that string becomes a key in every API response. Every frontend component reading entry.short\_description depends on it. * Field labels like "Short Description" are what editors see — those can change freely. Field UIDs like short\_description are the contract — those are locked in once you have published entries. * Use snake\_case consistently, be descriptive but concise, avoid abbreviations only your team understands. ### 5\. Show a content type definition and the resulting API response side-by-side * Open the Product content type in the Contentstack UI and point out the field labels and UIDs. * Switch to the API response JSON for a real Product entry — show how every field UID maps one-to-one to a JSON key. * Highlight that reference fields appear as stubs by default (just UIDs), and you add include\[\]=product\_line to resolve them. * Highlight that file fields return objects with url, filename, and MIME type. * Highlight the system fields that appear automatically: uid, locale, created\_at, updated\_at. ### 6\. Breaking changes vs. safe changes * Adding a new field to a content type is safe. Existing entries return null for the new field. Frontend code should handle null gracefully with optional chaining. * Removing a field is a breaking change. If the frontend reads product.media\[0\].url and you delete the media field, the component throws a runtime error. Remove the frontend dependency first, deploy, then delete the field. * Renaming a field UID breaks the contract immediately. The old key vanishes from API responses and the new key appears. Every line of frontend code referencing the old key fails. * Changing a field type is risky — converting a Number to Single Line Text changes the API output from 295 to "295". Code calling .toFixed(2) crashes. * Reordering fields in the schema has zero API impact — it only changes the editorial UI order. * The takeaway: treat field UIDs as public API surface, not internal details. ### 7\. TypeScript interfaces should mirror content type schemas * Show a TypeScript interface for the Product content type that matches the field UIDs exactly. * This gives you compile-time safety — if someone renames short\_description to summary, TypeScript catches the breakage before deployment. * Some teams generate TypeScript types directly from the content type schema using the CMA or the Contentstack CLI cs:content-type:get command. * The interface is your developer-side contract; the content type schema is your CMS-side contract. They should stay in sync. ### 8\. Global Fields: define once, reuse across content types, changes propagate * Global Fields solve the problem of maintaining identical field groups across multiple content types. * You create a Global Field under Settings > Global Fields — for example, an SEO Metadata global field with meta\_title, meta\_description, og\_image, and canonical\_url. * Then you add it to any content type. It appears in the editor as an expandable group, just like a regular Group field. * The difference: a Group field is defined inline inside one content type. A Global Field is defined centrally and referenced — changes propagate to every content type that uses it. * Think of it like a shared component in a design system. Define a Button once, use it on every page. * The API output is identical to a Group field — a nested JSON object. Frontend developers do not need to know whether it came from a Group or Global Field. ### 9\. When to use Global Fields vs. when not to * Use Global Fields when the same group of fields appears in three or more content types with identical structure: SEO metadata, address blocks, CTAs, social media links. * Do not use Global Fields for data that needs to be independently queryable — that should be a separate content type with references. A Category needs to be listed, filtered, searched — it cannot be a Global Field. * Do not use Global Fields when different content types need different variations of the field group. If Products need extra Schema.org fields that Pages do not, create two global fields or use a Group for the extension. * Do not use Global Fields for a group used by only one content type. A regular Group field avoids the management overhead. * Key distinction: References share content (one Product Line entry used by many products). Global Fields share structure (one field definition used by many content types). ### 10\. JSON Rich Text Editor: structured document tree, not HTML string * The JSON RTE is where structured content meets rich text — and it matters because HTML strings are opaque blobs you cannot traverse or transform. * An HTML RTE stores

Check out our Premium Widget

as a flat string. You cannot extract the product reference, validate the link, or repurpose the content for a mobile app. * The JSON RTE stores the same content as a tree of typed nodes — a root doc node, paragraph nodes, text leaf nodes with formatting flags like bold and italic. * Show the raw JSON structure: { "type": "doc", "children": \[{ "type": "p", "children": \[{ "text": "..." }\] }\] }. * Every node has a type, a UID, optional attrs, and children. Text nodes are leaf nodes with a text property and boolean formatting properties. * This tree is fully traversable. A mobile app can extract just the text. A voice assistant skips images. A web app renders every node with custom components. ### 11\. Embedded entries and assets as reference nodes; rendering with @contentstack/utils * Editors can embed entries from other content types directly within JSON RTE content — inline or as blocks. * The JSON RTE stores these as reference nodes with entry-uid and content-type-uid attributes. The data is not duplicated; it is referenced. * To get the full embedded entry data in the API response, you must add include\_embedded\_items\[\]= to your API call. Without it, you get bare UIDs and embedded entries silently disappear from rendered output. * On the frontend, install @contentstack/utils and use jsonToHtml to convert the JSON tree to HTML. Pass paths to specify which fields contain JSON RTE data. * For custom rendering, use the renderOption parameter with renderNode handlers for each node type — including a reference handler for embedded entries and assets. * In React, you can build a component-based renderer where each node type maps to a React component, giving you full control over rendering. ### 12\. Custom RTE plugins: extending the editor toolbar via Developer Hub * Custom plugins add toolbar buttons, custom element types, paste behaviors, and keyboard shortcuts to the JSON RTE editor. * Plugins are built with @contentstack/app-sdk and deployed through Developer Hub as Contentstack apps with an RTE Plugin location. * A plugin inserts custom node types into the JSON tree — for example, a "Callout" button that creates a node of type callout with a style attribute. * The custom nodes appear in the API response as regular nodes with your custom type values. Your frontend renderer must handle them — if it does not, they render as blank space. * This is a three-way coordination: the plugin developer defines the node type, the content modeler enables the plugin on specific JSON RTE fields, and the frontend developer implements the renderer. Document the custom node schemas the same way you document content type schemas. ## Screen: What to Show Outline item Screen instructions 1\. Mindset shift Show a wireframe of a traditional product page with everything in one record. Then switch to the Contentstack Content Models list showing Product, Product Line, Category, Page as separate types. 2\. Three questions Display the three questions as a text overlay or slide. Point at each one while explaining. 3\. Veda example Open the Product content type in Content Models. Scroll through the field list: title, url, short\_description, description, price, media, product\_line (reference), category (reference). Then open Product Line and Category to show their schemas. Show the multi-channel reuse table as a slide or overlay. 4\. API contracts Split screen: left side shows the Content Type Builder with field labels and UIDs visible. Right side shows a code editor with the equivalent JSON API response. Draw attention to how the UID column maps to JSON keys. 5\. Side-by-side definition and response Open the CMA endpoint GET /v3/content\_types/product in a REST client (Postman or terminal with curl + jq). Show the schema array. Then fetch a Product entry from the CDA at GET /v3/content\_types/product/entries/{uid} and place both responses side by side. 6\. Breaking changes In the Content Type Builder, hover over a field UID and demonstrate what happens conceptually if you rename it. Show a terminal or browser console with a "Cannot read property of undefined" error to illustrate the frontend breakage. Show the safe path: adding a new field and showing it returns null on existing entries. 7\. TypeScript interfaces Switch to VS Code. Show a TypeScript interface for Product that mirrors the content type UIDs. Show the compiler catching a wrong property name with a red underline. 8\. Global Fields Navigate to Settings > Global Fields. Create or open the SEO Metadata global field showing meta\_title, meta\_description, og\_image, canonical\_url. Then open a content type (e.g., Page) and show the SEO Metadata global field embedded as an expandable group. Show the API response with the nested seo object. 9\. Global Fields decision Show a simple decision table as a slide: "3+ content types with identical shape = Global Field. Independently queryable = Reference. One content type only = Group field." 10\. JSON RTE Create or open a JSON RTE field in the entry editor. Type a paragraph with bold text. Then switch to the API response and show the raw JSON document tree — the doc node, p node, text nodes with bold: true. Contrast with an HTML RTE field that returns a flat HTML string. 11\. Embedded entries and rendering In the JSON RTE editor, click the Embed Entry toolbar button and insert an entry. Show the API response with the reference node containing entry-uid and content-type-uid. Switch to VS Code and show the @contentstack/utils import and jsonToHtml call with a renderOption that handles the reference node type. 12\. Custom RTE plugins Show the Developer Hub > New App screen. Show a plugin code snippet in VS Code that registers a custom toolbar button. In the entry editor, click the custom button and show the custom node appearing. Then show the API response containing the custom node type. ## Veda Scenario Thread * Open with the problem: Veda currently has a monolithic "Product Page" template in their old CMS. Every product bundles title, description, price, images, product line text, category text, and SEO fields into one record. The marketing team wants to launch a mobile app, a marketplace feed for partners, and an email campaign — all pulling from the same product data. * In section 1-2, explain why the page model fails for Veda: the marketplace feed needs title, price, and one image without any HTML. The mobile app needs a product summary without layout artifacts. The email needs a hero image and a link. You cannot serve six channels from one page template. * In section 3, walk through the Veda decomposition: Product with its eight fields, Product Line (Digital Dawn, Urban Armor, Heritage Craft), Category (Earrings, Necklaces, Bracelets, Rings), and Page with modular blocks. Show how the Matrix Link Bracelet references Digital Dawn and Bracelets. * In section 4-6, use the Product content type as the live example of the API contract. Show the Matrix Link Bracelet's API response. Demonstrate that renaming short\_description to summary would break the ProductCard component. Show that adding a sale\_price field is safe — existing entries return null. * In section 7, show the TypeScript interface for Veda's Product type mirroring the content type schema. * In section 8-9, add the SEO Metadata global field to both the Product and Page content types for Veda. Show how one update to the global field (adding a robots\_directive field) propagates to both types. * In section 10-11, open the Veda Product's description field as a JSON RTE. Show an editor embedding a "Product Comparison" entry within the product description. Show the raw JSON with the reference node. Render it with @contentstack/utils. * In section 12, mention that Veda could build a custom "Care Instructions" callout plugin for the JSON RTE, allowing editors to insert standardized care instruction blocks within product descriptions. ## Transitions 1 to 2: "So if we are not thinking in pages, how do we decide what gets its own content type? Three questions." 2 to 3: "Let us apply those three questions to the Veda jewelry catalog and see what content types fall out." 3 to 4: "Now that we have our four content types, here is the part most people miss — every field UID you just defined is a public API contract." 4 to 5: "Let me prove that to you by putting the content type definition next to the actual API response." 5 to 6: "So what happens when someone changes that contract? Some changes are safe, and some break everything." 6 to 7: "The best defense against accidental breakage is TypeScript — make the compiler enforce the contract." 7 to 8: "We have been looking at individual field definitions, but some field groups show up on every content type. That is where Global Fields come in." 8 to 9: "Global Fields are powerful, but they are not always the right tool — here is how to decide." 9 to 10: "Now let us talk about the trickiest field type: rich text. Specifically, the JSON Rich Text Editor." 10 to 11: "The real power of the JSON RTE is not just formatting — it is embedding other entries and assets right inside the text." 11 to 12: "And if the built-in toolbar is not enough, you can extend the JSON RTE with custom plugins." Closing to Video 4: "We have covered how to model domain concepts, lock in API contracts, and handle rich text. In the next video, we will connect these content types together with references, modular blocks, and taxonomies — the relationship layer that makes your content model actually work." ## Common Mistakes to Call Out 1. Recreating page layouts as content types. Building a "Homepage" content type with fields for hero\_section, featured\_products\_carousel, and newsletter\_signup locks content into a single layout and throws away all reuse benefits. Use Modular Blocks or references to compose pages from independent content pieces. 2. Storing structured data inside rich text fields. Putting the product line description inside a JSON RTE as formatted text makes it impossible to query by product line, filter products, or generate collection pages. If data needs to be queried or reused independently, it belongs in its own content type with discrete fields. 3. Duplicating content instead of referencing it. Copying the product line name and description into every product entry creates maintenance burden and guarantees inconsistency. Use Reference fields to point to a single Product Line entry. 4. Treating field UIDs as internal details. Field UIDs are public API field names. Choosing a UID like f1 or temp\_field makes the API response unreadable and forces frontend developers to guess. Use meaningful, stable UIDs from the start. 5. Changing field types without coordinating with frontend teams. Converting a Date field to Single Line Text changes the API output from an ISO 8601 string to freeform text. The frontend date formatter breaks. Treat type changes as a contract renegotiation. 6. Ignoring optional fields in frontend code. When a new field is added, existing entries do not have a value for it. Components that assume every field has a value crash with "Cannot read property of undefined." Always use optional chaining and null checks. 7. Creating global fields for data that should be references. A "Featured Product Line" global field with line\_title, line\_description, and line\_image embedded in every Product creates data duplication. That data belongs in a Product Line content type with Reference fields. Global fields share structure, not content. 8. Modifying global fields without checking downstream impact. Removing a field from a global field used by 12 content types simultaneously breaks the API contract for all 12. The blast radius is proportional to reuse. Always audit usage before editing a global field. 9. Not handling embedded entries in the frontend renderer. When editors embed entries in a JSON RTE, the API response contains reference nodes. If the renderer does not handle the reference node type, those entries silently disappear from the output. 10. Forgetting include\_embedded\_items\[\] in the API call. Without this parameter, embedded entry references contain only UIDs, not actual data. Embedded content vanishes from the rendered page with no error — it just disappears. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 3 — Structured Content and API Contracts** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 19 — Video Production Plan : Video 4 — Composition, Query Performance, and Modeling in Practice #### Lesson text # Video 4 — Composition, Query Performance, and Modeling in Practice Attribute Details Course 2 (Content Modeling), Modules 2.2 and 2.3 Covers Lessons 2.2.1, 2.2.2, 2.2.3, 2.3.1, 2.3.2, 2.3.3, 2.3.4, 2.3.5 Priority Core Length 20-28 min Format Live model review using the Veda scenario Status Not started ## Why This Video Matters This is where modeling theory becomes real-world decision making. Learners see how to translate business requirements into content types and how to audit and improve existing models. ## Outline 1. References vs Modular Blocks: when to use each * References: link to independent entries (Product references a Category) * Modular Blocks: composable, inline content sections (hero, feature grid, testimonial) 2. Show a reference field and a modular blocks field in the editor, then compare their API output 3. Taxonomy, tags, and classification: organizing content beyond references 4. Query performance: payload size, include depth tradeoffs, keeping queries efficient 5. Start with a Veda business requirement and translate it into content types step by step 6. Auditing a messy content model: identify duplicated fields, missing references, unclear naming 7. Model sprawl: what 50 content types that should be 15 looks like, how to prevent it 8. Modeling for multiple channels: same content, different presentations 9. Localization strategy: localized fields vs localized entries, fallback behavior 10. Governance frameworks: naming conventions, review processes, documentation standards ## Key Lines "Many performance problems begin as modeling problems." "The cleanest editor experience and the cleanest API are often connected." "A good content model scales with your team. A bad one scales against it." ## Detailed Talking Points ### 1\. References vs Modular Blocks: when to use each * References create pointers to independent entries. A Product references a Category. The Category lives on its own, has its own publish state, its own URL in the Management API. Update the Category once, every Product that references it picks up the change. * Modular Blocks are inline composable sections: hero, feature grid, testimonial strip, CTA. The data lives inside the parent entry. No separate entry, no separate lifecycle. * The decision rule: if the content is reused across multiple entries and has its own editorial lifecycle, use a reference. If the content belongs to one page and nobody would ever browse or search for it independently, use a modular block. * Common mistake: creating a separate hero\_banner content type and referencing it from a page when that hero only ever appears on one page. That is unnecessary indirection. Use a modular block instead. * Opposite mistake: embedding author data as a modular block inside articles. Now every article carries its own copy of the author bio. Updating the bio means editing every article. References solve this. * Extensions (custom fields) exist too, but they solve a different problem: specialized editorial UI like color pickers or third-party lookups. Higher build cost, only reach for them when native fields cannot handle the UX requirement. ### 2\. Show a reference field and a modular blocks field in the editor, then compare their API output * Open a Veda page entry that has both a reference field (e.g., testimonials) and a modular blocks field (e.g., page\_sections). Show them side by side in the editor. * Reference field: editor picks from existing entries using an entry picker. The referenced entries exist independently. * Modular blocks field: editor adds, removes, and reorders blocks inline. Block data is tightly coupled to this entry. * Fetch the entry via the Delivery API without include\[\]. Show that reference fields return only UIDs and \_content\_type\_uid -- not the actual content. Modular blocks return full inline data with no extra resolution needed. * Add ?include\[\]=testimonials to the query. Now the referenced entries resolve inline. Stress that this is an explicit step developers must remember. * Show the JSON side by side: references produce separate entry payloads nested under the reference key; modular blocks produce an array of objects keyed by block type. ### 3\. Taxonomy, tags, and classification: organizing content beyond references * Contentstack has three classification mechanisms: Taxonomy (governed, hierarchical, cross-content-type), Tags (freeform string arrays, zero setup), and reference-based categorization (categories as full content entries). * Taxonomy: centrally managed under the Taxonomy section in the stack. You define terms in a hierarchy. Editors pick from controlled vocabularies. Queryable across content types with taxonomies.product\_line syntax. * Tags: easy to add, impossible to govern. After six months you get "AI", "A.I.", "ai", "artificial-intelligence" all meaning the same thing. Queries miss content. * Reference-based categorization: best when the category itself is a rich content entity with its own page, description, and metadata. But querying across content types requires separate API calls per type. * Decision framework: use taxonomies for governed facets that power navigation and filtering, tags for informal internal labels, references for content-rich categories with their own pages. * For Veda: product\_line and category taxonomies enable cross-content-type queries like "show me everything in Digital Dawn" with a single API call. ### 4\. Query performance: payload size, include depth tradeoffs, keeping queries efficient * Every content model is also a query contract. The fields, references, and modular blocks you define determine the size, speed, and cost of every API response. * Include depth: default is 0 (references return as UIDs only). Each level of include\[\] adds latency and payload size. One level might be 80ms. Two levels might be 200ms. Three might exceed 400ms. * Max useful depth is usually 2-3. If your model requires more, that is a signal to flatten the model, not work around the depth limit. * Payload budgets: aim for individual entry responses under 50KB, list queries under 200KB. Rich text fields in referenced entries, modular blocks with many instances, and multi-reference fields with large arrays are the main bloat drivers. * Use only\[BASE\]\[\] for list views to return only the fields the UI needs. A product card showing title, thumbnail, and price does not need the full rich text description. * Normalized vs denormalized: pure normalization means many references and slow queries. Pure denormalization means duplicate data and update pain. The practical middle ground: normalize entities with independent lifecycle, denormalize display-only data that rarely changes. * Worked example: a naive product model with 5 levels of reference depth resolves 28 entries per request. Flattened to 2 levels, it resolves 7 entries. Same data, fraction of the cost. ### 5\. Start with a Veda business requirement and translate it into content types step by step * Start with the brief: "Veda wants to add gift sets that bundle 2-4 products, with a name, description, hero image, and optional gift message. Gift sets appear in Digital Dawn and Charmed Revival product lines. Support English and Spanish." * Step 1: identify entities. Read the brief, underline nouns that have their own identity and lifecycle. Gift Set, Product (already exists), Product Line (already exists). Not "Gift Set Page" -- that is presentation. * Step 2: determine relationships. Gift Set contains Products (many-to-many reference). Gift Set appears in Product Lines (many-to-many reference). * Step 3: define fields. Gift Set gets title (mandatory, unique), URL, description (JSON RTE), hero image, gift message, products (multi-reference, mandatory), product\_line (multi-reference). * Step 4: decide what NOT to model. Inventory, cart state, pricing -- those belong in the commerce system, not the CMS. Draw a clear boundary between editorial content and transactional data. * Step 5: validate with real entries and API responses before committing. Create 2-3 entries with real content, fetch via the Delivery API, confirm the JSON matches what the frontend expects. ### 6\. Auditing a messy content model: identify duplicated fields, missing references, unclear naming * Audit when you see signals: 40+ field content types, fields named \*\_v2 or temp\_\*, editors consistently skipping fields, developers getting API responses full of unused keys. * Red flags: content types with 40+ fields, fields empty across 90% of entries, confusing names like cta\_link\_2 or misc\_data, reference chains 4+ levels deep, dual-purpose content types. * Step 1: export schemas via the Management API, sort by field count. Highest field counts are your first audit targets. * Step 2: analyze field population rates. Fields with less than 10% population are candidates for removal. * Step 3: interview editors. "Walk me through creating an entry. Where do you pause? Which fields do you skip?" * Step 4: map API consumers. Which frontends read which fields? Fields that no consumer reads and no editor populates are dead weight. * The 47-field Product example: split into Product (core, 10-12 fields), Product Specs (referenced), SEO Metadata (Global Field). Inventory and pricing fields removed from the CMS entirely. * UID changes are coordinated migrations, not casual renames. Changing a UID breaks every API consumer that references the old key. ### 7\. Model sprawl: what 50 content types that should be 15 looks like, how to prevent it * Model sprawl: too many content types, each too small to justify its existence, connected by deep reference chains. * Warning signs: more content types than entries for some types (a CallToAction type with 3 entries), editors cannot find where to create content (35+ options in the dropdown), assembling one page requires touching 6+ content types. * The "one content type per component" anti-pattern: mapping every React component to its own content type. A HeroBanner with 4 fields, a FeatureCard with 3 fields, a StatCounter with 2 fields. None of these are content entities. They are field groups masquerading as content types. * The fix: use Modular Blocks for component-level structures, Global Fields for reusable field groups, standalone content types only for entities with independent lifecycle. * The rule of three: do not extract a reusable pattern until you have three concrete instances. One testimonial page does not justify a Testimonial content type. * Real example: a startup with 35 content types and 200 entries consolidated to 9 content types. Same website, same content, fraction of the complexity. * Healthy ratios: a marketing site needs 5-10 types, a corporate site 10-20, a media platform 8-15. 35 types with 200 entries is a red flag. ### 8\. Modeling for multiple channels: same content, different presentations * Core principle: structure content for meaning, not for presentation. Channel-specific rendering is the frontend's job. * Channel-neutral content: structured JSON RTE, a single high-res image (use Image Delivery API transforms for sizing), key\_features as an array. Works for web, mobile app, voice assistant, email. * Channel-coupled content (anti-pattern): web\_hero\_html, mobile\_short\_description, email\_preview\_text, kiosk\_display\_mode. Every new channel requires new fields. Every copy change requires updating multiple fields. * Practical rules: store content as structured data not markup, use Image Delivery API for responsive images, keep field names channel-agnostic (short\_description not mobile\_description), use include\[\] strategically per consumer. ### 9\. Localization strategy: localized fields vs localized entries, fallback behavior * Localization operates at three levels: stack-level language configuration, field-level localization settings, and entry-level data. * Field-level decision: mark fields as non-localizable by default. Only opt in for text that editors actually translate. Title, description, CTA labels, alt text -- localize these. Dates, SKUs, reference fields, booleans -- keep universal. * Common mistake: making a reference field localizable. Now the French version of a product silently points to a different category than the English version. Nothing in the UI flags the inconsistency. * Fallback hierarchy: design it before launch. fr-ca falls back to fr-fr, which falls back to en-us. This lets you launch with only base-language content and progressively translate. * Locale-specific publishing: editors switch locale in the entry editor, translate localizable fields, and publish the localized version independently. The Delivery API returns the best available version per field based on the fallback chain. * Prioritize translations by fallback usefulness: Japanese first (fallback to English is least useful for Japanese readers), then French, then regional variants. ### 10\. Governance frameworks: naming conventions, review processes, documentation standards * Naming conventions are the highest-impact, lowest-cost governance tool. Content type UIDs: snake\_case (blog\_post, not blogPost or bp). Field UIDs: snake\_case, short but unambiguous. Display names: human-readable for editors. * Bad UIDs: blogPost (camelCase), bp (cryptic), content\_blog\_post\_v2 (version numbers signal migration debt), page\_component\_hero\_banner\_module (over-qualified). * Field descriptions: every field should have a populated description. "Page title shown in browser tabs and search results. Keep under 60 characters." costs 30 seconds to write, saves hours of confusion. * Roles and permissions: restrict content type modification to Admin roles. Give editors Content Manager roles scoped to their content types. This prevents accidental schema changes. * Lightweight review process: maintain a decision log for structural changes. Three questions per entry: what changed, why, who decided. Not a formal approval workflow -- a log. Takes 2 minutes. * Threshold: adding an optional field -- just do it and log. Creating a new content type, removing a field UID, changing a reference target -- discuss first, then log. * Use built-in guardrails: mandatory fields for minimum viable entries, unique constraints for identifiers, regex validation for slugs and SKUs, Select fields instead of freeform text for known value sets. ## Screen: What to Show Outline Item / Segment What to Show on Screen / Instructions Outline items 1-2 (References vs Modular Blocks) Open the Veda stack in Contentstack. Navigate to a Page content type that has both a reference field (e.g.,  testimonials  referencing the Testimonial content type) and a modular blocks field (e.g.,  page\_sections ). Show the content type schema view first: point out the reference field config (which content types it can reference, single vs multi) and the modular blocks config (block type definitions with their inline fields). Switch to an entry. Show the reference field picker UI (searching and selecting existing entries) vs the modular blocks composer (adding blocks, reordering with drag-and-drop). Open a terminal or API client (Postman, Insomnia, or curl). Fetch the entry without  include\[\]  -- show the raw UIDs for references. Then add  ?include\[\]=testimonials  and show the resolved data. Side-by-side the two JSON responses. Show the modular blocks portion of the response -- full inline data, no extra parameters needed. Outline item 3 (Taxonomy, tags, classification) Navigate to the Taxonomy section in the left nav of Contentstack. Show the  product\_line  taxonomy with its terms (Digital Dawn, Urban Armor, etc.). Open a Product entry and show the taxonomy field where editors assign terms from the controlled vocabulary. In the terminal, run a taxonomy query:  ?query={"taxonomies.product\_line":{"$in":\["digital\_dawn"\]}}  -- show results spanning content types. Contrast with a freeform tags field on another entry. Type a few inconsistent tags to illustrate the governance problem. Outline item 4 (Query performance) Show a product entry with deep references: product -> product\_line -> related\_products -> their product\_lines. Diagram or whiteboard the reference tree. Fetch the entry with all includes and show the response time and payload size in the API client. Then fetch with  only\[BASE\]\[\]=title&only\[BASE\]\[\]=slug&only\[BASE\]\[\]=thumbnail  -- show the dramatically smaller response. Optionally show a before/after payload size comparison on screen (e.g., 85KB vs 4KB for a list view). Outline item 5 (Translating requirements) Put the Veda gift set brief on screen (text overlay or slide). Walk through underlining the nouns that become entities. Whiteboard or diagram the entity-relationship map: Gift Set -> Products, Gift Set -> Product Lines. Switch to Contentstack, create the Gift Set content type live (or show a pre-built one). Walk through each field and explain why it exists. Create a sample Gift Set entry with real Veda product names. Fetch it via the API and show the JSON. Outline item 6 (Auditing) Show a deliberately messy content type schema (pre-built for the video): 40+ fields, names like  banner\_v2 ,  temp\_promo ,  old\_description . Scroll through it in the content type builder. Run the Management API curl command to export schema and pipe through  jq  to show field counts per content type. Show a spreadsheet or table with field population rates (percentage of entries where each field has data). Highlight fields at 5-10% population. Outline item 7 (Model sprawl) Show a stack sidebar with 30+ content types listed. Scroll through it. Point out types with 2-3 entries. Show the "before" model: 35 types, 200 entries. Then show the "after": 9 types, same content. Use a slide or diagram with both side by side. Outline items 8-9 (Channels and localization) Show a channel-neutral Product entry: structured JSON RTE, single hero image, key\_features array. Show the Image Delivery API in action: append  ?width=400&format=webp  to an image URL, show the resized result. Switch locales in the entry editor. Show how non-localizable fields (SKU, dates) are read-only in the localized view. Translate a localizable field (product name) into Spanish. Show the locale fallback config under Settings > Languages. Diagram the fallback hierarchy. Outline item 10 (Governance) Show the Roles & Permissions screen in Contentstack. Walk through Admin vs Content Manager role differences. Show a well-documented content type: populated Description field, field descriptions with clear guidance, regex validation on a slug field. Contrast with an undocumented content type: empty descriptions, cryptic field names. Show a sample decision log (Markdown file in the repo or a Notion page). ## Veda Scenario Thread The entire video uses Veda as the connective tissue: 1. **References vs Modular Blocks:** Veda's Product references Category and Product Line (independent entities, shared across products). Veda's landing pages use modular blocks for hero, feature grid, and CTA sections (page-specific, no reuse). 2. **API comparison:** Fetch a Veda product page. Show testimonials as unresolved UIDs, then resolved with include\[\]. Show page\_sections as inline modular block data. 3. **Taxonomy**: Veda classifies products by product\_line (Digital Dawn, Urban Armor) and category (Earrings, Bracelets) using taxonomies. Show a cross-content-type query: "everything in Digital Dawn" returns products, product lines, and pages in one call. 4. **Query performance:** The Veda product detail page resolves product\_line, category, and 5 related products. At two levels deep, that is 17 entries per request. Show how flattening (inline category\_path, capped related\_products) drops it to 7 entries. 5. **Translating requirements:** Take the Veda gift set brief live. Walk from business paragraph to entity identification to content type creation to sample entry to API response. 6. **Auditing:** Show a hypothetical "inherited Veda stack" with model debt: a 47-field Product type, fields named promo\_banner\_v2, empty legacy\_tagline fields. Audit it on screen. 7. **Model sprawl:** Show what happens if someone mapped every Veda page component to its own content type: HeroBanner, FeatureCard, TestimonialSlide, StatCounter. 30+ types, 150 entries. Consolidate to the actual Veda model with modular blocks. 8. **Channels:** Veda serves the same product data to web (full layout) and mobile app (card view). Same entry, different only\[BASE\]\[\] projections and include\[\] depths per consumer. 9. **Localization:** Veda launches in English and Spanish. product\_name and description are localizable. SKU, price, release\_date, reference fields are not. Show the fallback: es-mx falls back to es-es, which falls back to en-us. 10. **Governance:** Veda's naming conventions: product, product\_line, gift\_set (snake\_case UIDs). Field descriptions populated. Content type descriptions state ownership and usage. Decision log records why gift\_set was added. ## Transitions 1 to 2: "Now that you know the rules, let me show you what this actually looks like in the editor and the API." 2 to 3: "References and modular blocks handle composition -- but classification is a different problem entirely." 3 to 4: "Every classification and composition choice has a cost, and that cost shows up in your API responses." 4 to 5: "Knowing the performance tradeoffs is useful, but let me show you how to apply all of this from scratch with a real business requirement." 5 to 6: "That was a greenfield model -- now let me show you what happens when you inherit someone else's model and need to fix it." 6 to 7: "Auditing catches bloated content types, but the opposite problem -- too many tiny content types -- is just as damaging." 7 to 8: "Once the model is clean, make sure it works for every channel, not just the website." 8 to 9: "Multi-channel is about delivery variation -- localization is about language variation, and the modeling decisions are just as important." 9 to 10: "A good model degrades without governance -- naming conventions, role restrictions, and a lightweight decision log keep it healthy over time." Closing to Video 5: "You now know how to compose, query, audit, and govern content models. In Video 5, we shift to the API layer -- how to actually fetch, filter, and deliver this content to your frontends." ## Common Mistakes to Call Out 1. **Using references for content that is never reused.** A separate hero\_banner content type referenced from one page adds lifecycle overhead, publish-state complexity, and an extra include\[\] for zero reuse benefit. Use a modular block. 2. **Using modular blocks for content that needs independent lifecycle.** Embedding author bios as modular blocks means every article carries its own copy. Updating an author bio requires editing every article individually. 3. **Forgetting** **include\[\]** **on reference fields.** The frontend receives UIDs instead of content. This is the single most common "why is my data missing" question from new Contentstack developers. 4. **Resolving all references on every query.** Fetching articles with include\[\]=author&include\[\]=category&include\[\]=related\_articles&include\[\]=tags when the list view only shows title and date. Use only\[BASE\]\[\] for list views. 5. **Ignoring payload size until production.** Development datasets are small. A 2,000-entry catalog with rich text and images exposes every over-fetching pattern. Test with realistic data volumes early. 6. **Modeling deep hierarchies as chained references.** Category trees as category -> parent -> grandparent -> root create unbounded reference depth. Store the hierarchy as a denormalized path field and use a single reference to the leaf. 7. **Using freeform tags for user-facing navigation.** After six months: "AI", "A.I.", "ai", "artificial-intelligence" all meaning the same thing. If classification drives navigation or filtering, use taxonomies. 8. **Mapping frontend components 1:1 to content types.** Every React component gets its own content type. 35 types, 200 entries. Editors spend more time navigating the model than writing content. 9. **Localizing fields that should be universal.** Making a reference field or date field localizable means the French version silently points to a different category than English. Default to non-localizable, opt in per field. 10. **No naming conventions.** Five developers create content types with five different naming styles. Onboarding a new developer six months later requires archaeology instead of reading documentation. 11. **Skipping the relationship mapping step.** Jumping to field definitions without mapping entity relationships produces content types that either duplicate data or miss connections. 12. **Treating the content model as final.** A content model is a living artifact. Build with the expectation of iteration, not perfection. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 4 — Composition, Query Performance, and Modeling in Practice** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 20 — Video Production Plan : Video 5 — API Architecture, Authentication, and Query Surface Choice #### Lesson text # Video 5 — API Architecture, Authentication, and Query Surface Choice Attribute Details Course 3 (APIs and Developer Tooling), Module 3.1 Covers Lessons 3.1.1, 3.1.2, 3.1.3, 3.1.4, 3.1.5 Priority Critical Length 18-25 min Format Screencast (Postman/terminal + slides for architecture diagrams) Status Not started ## Why This Video Matters This clarifies the boundaries developers most often confuse. Most API mistakes are boundary mistakes, not syntax mistakes. ## Outline 1. Two APIs, two jobs: Delivery API (read-only, CDN-backed, fast) vs Management API (CRUD, authenticated, for tooling) 2. When to use which: frontend always uses Delivery; CI/CD, migrations, and admin scripts use Management 3. Preview vs published delivery concerns 4. Regions and clouds: NA, EU, Azure NA, Azure EU — each has different base URLs 5. Show where to find the correct base URL for your stack 6. REST vs GraphQL tradeoffs: REST for simple queries and full SDK support; GraphQL for precise field selection and reducing over-fetching 7. Show the same query in REST and GraphQL side-by-side, compare payload sizes 8. Authentication: Delivery Tokens (environment-scoped, read-only) vs Management Tokens vs OAuth 9. Token placement and credential scoping — demonstrate creating and using each token type 10. Rate limits: know the limits, handle 429 responses gracefully, implement backoff 11. Error codes walkthrough: common errors (401, 404, 422, 429) and what to do about each ## Key Lines "Most API mistakes are boundary mistakes, not syntax mistakes." "Choose the API by intent, not by convenience." "If a token ends up in the wrong runtime, that is an architecture issue, not a documentation issue." ## Detailed Talking Points ### 1\. Two APIs, two jobs * Contentstack has two separate API planes: the Content Delivery API (CDA) and the Content Management API (CMA). They exist for fundamentally different reasons. * CDA is read-only, CDN-backed, optimized for high-volume frontend traffic. It only returns published content. * CMA handles CRUD operations: creating entries, updating content types, managing workflows, publishing, branch administration. * These are two different reliability planes. CDA is designed for many reads, low latency, aggressive caching. CMA is designed for fewer requests, higher privilege, explicit auditability. * Different token types protect each plane. Delivery tokens are environment-scoped and read-only. Management tokens are stack-level and read-write. * Different blast radius: if a delivery token leaks, an attacker can read published content. If a management token leaks, an attacker can modify or delete your entire stack. * Think of it as: delivery plane vs control plane. Keep them separated in your codebase, your token strategy, and your mental model. ### 2\. When to use which: the decision framework * Do not choose the API by convenience or by what returns results during local dev. Choose by intent. * Five-question decision sequence: (1) What is the intent -- render or manage? (2) What data state -- published or draft? (3) Where does this call run -- browser/edge or backend? (4) What token can safely exist in this runtime? (5) What happens if this endpoint is abused? * If the intent is rendering published content for users: CDA. Always. * If the intent is content operations -- creating, updating, deleting, publishing, workflow actions: CMA. Only in trusted backends. * If your answers to these five questions mix two intent classes in one code path, split the design before writing code. * CMA has GET endpoints. That does not make them delivery endpoints. Classify by intent, not HTTP verb. * Common mistake: using CMA reads in frontend code because "it works locally." It does work -- until you ship a management token to the browser. ### 3\. Preview vs published delivery concerns * CDA returns only published content for a given environment. If an editor saves a draft, CDA will not reflect it. * For draft or preview content, use the Preview API with preview tokens -- a separate retrieval context. * Preview tokens are still read-path credentials. They should never grant management capabilities. * In Veda's case: the storefront uses CDA for production traffic. The editorial preview experience uses the Preview API so editors see unpublished changes. ### 4\. Regions and clouds * Your stack's region is locked at creation. It determines every API base URL your code targets. You cannot change it later. * Contentstack operates across seven regions on three cloud providers: AWS (NA, EU, AU), Azure (NA, EU), GCP (NA, EU). * Each region has its own set of base URLs for CDA, CMA, GraphQL, Preview, Assets, and all platform services. * AWS NA is the "default" -- it uses the .io TLD (cdn.contentstack.io). Every other region uses .com with a prefix (eu-cdn.contentstack.com, azure-na-cdn.contentstack.com). * The .io vs .com TLD difference is a common copy-paste error. If you switch from NA to EU and only change the prefix but keep .io, your requests will fail silently. * Reasons for region choice: data residency (GDPR), latency, cloud provider alignment with existing infrastructure. ### 5\. Finding the correct base URL * Dashboard: Settings > Stack shows the region. * Browser URL gives a hint: eu-app.contentstack.com means AWS EU, azure-na-app.contentstack.com means Azure NA. * Use the SDK's built-in region constants (Contentstack.Region.EU, Contentstack.Region.AZURE\_NA, etc.) -- the SDK constructs correct endpoints automatically. * For endpoints beyond the Delivery SDK (Preview host, Application host for Live Preview), use the @timbenniks/contentstack-endpoints package or reference the official regions data at artifacts.contentstack.com/regions.json. * Quick diagnostic: if credentials are correct but you get 401 or empty results, test the same request with curl against different region base URLs. One returns 200, the other returns 401. The 200 one is your actual region. ### 6\. REST vs GraphQL tradeoffs * Both REST CDA and GraphQL CDA are read-only, use the same delivery tokens, return only published content, and sit behind CDN infrastructure. * REST strengths: simple and predictable URLs, strong CDN caching (GET requests are inherently cacheable), mature SDK support, include\[\] for reference resolution, rich query operators ($in, $gt, $regex, etc.). * REST limitation: over-fetching. You get all fields even if you only need two. Fixed response shape. Multiple round trips for unrelated content types. * GraphQL strengths: request exactly the fields you need, fetch from multiple content types in a single query, schema introspection, type safety with codegen. * GraphQL limitations: no mutations (all writes go through REST CMA), query complexity limits for deeply nested references, POST-based requests are harder to cache at CDN edge, SDK support is primarily REST-oriented. * GraphQL does not support the SDK include\[\] syntax for references. It uses the Relay-style Connection pattern instead. * Neither is "better." Choose per-query based on actual needs: payload size sensitivity, query complexity, caching requirements, team familiarity. ### 7\. Same query in REST and GraphQL side-by-side * Show fetching blog posts with author references in REST: GET /v3/content\_types/blog\_post/entries?environment=production&include\[\]=author with api\_key and access\_token headers. * Show the same query in GraphQL: a query selecting only title, url, and authorConnection with specific fields. * Compare the response payloads. REST returns every field on blog\_post and author. GraphQL returns exactly what you asked for. * Point out the Connection syntax in GraphQL for references and assets -- this is Contentstack-specific and catches people off guard. * Call out that both use the same delivery token. The auth model is identical. The query model is different. ### 8\. Authentication: token types and their roles * Three credential types to know: Delivery Tokens, Management Tokens, and OAuth tokens. * Delivery Tokens: environment-scoped, read-only, safe for client-side code. They can only read published content for one specific environment. * Management Tokens: stack-level, read-write, never expose to clients. They can create, update, delete entries, modify content types, manage workflows. If this token leaks, your stack is compromised. * OAuth: used for Contentstack Apps. Enables user-context-aware operations with consent flows. * Design your credential model around four questions: Who is the actor? What plane is accessed? What is the minimum scope? How will this credential be rotated? * Token selection should be the output of this security model, not the starting point. ### 9\. Token placement and credential scoping * Show creating a delivery token in the dashboard: Settings > Tokens > Delivery Tokens. Note it is scoped to a specific environment. * Show creating a management token: Settings > Tokens > Management Tokens. Note the stack-level scope and permission configuration. * Code example: separate deliveryClient and managementClient configs in api-clients.ts. The delivery client uses cdn.contentstack.io with access\_token. The management client uses api.contentstack.io with authorization. * Architectural rule: frontend request handlers can import deliveryClient only. CMA calls stay in trusted back-office services. Enforce this with linter rules or module boundaries. * Smell test: if revoking one token would break many unrelated systems, your security boundary is too broad. One credential per service responsibility. ### 10\. Rate limits: know them, respect them, handle 429 * CDA rate limits are generous (paid plans: ~200 req/s) because delivery traffic is cacheable and read-only. * CMA rate limits are tighter (~10 req/s default) because it handles write operations. This is where rate limiting becomes a daily concern during migrations, bulk publishes, and automated workflows. * Read X-RateLimit-Remaining on every response -- not just errors. Proactively throttle before hitting the wall. * When you get a 429: exponential backoff with jitter. Formula: delay = min(baseDelay \* 2^attempt + random(0, jitterMax), maxDelay). * Jitter is not optional. Without it, concurrent clients synchronize their retries and create a thundering herd -- all retrying at the same instant, re-triggering the overload. * CMA write retries have an idempotency danger: if a POST times out but the server processed it, retrying creates a duplicate entry. Use UID-based updates when possible, or check for existence before retrying creates. ### 11\. Error codes walkthrough * 401 Unauthorized: wrong or missing token. Could also mean correct token but wrong region endpoint. Do not retry -- fix the credential or region. * 404 Not Found: wrong content type UID, wrong entry UID, or malformed API path. Could also mean correct UID but wrong region. One edge case: brief 404 right after publishing due to propagation delay. * 412 Precondition Failed: version conflict on CMA entry update, or region/credential mismatch. For version conflicts: re-fetch the entry, get the current version, merge your changes, resubmit. * 422 Unprocessable Entity: your JSON is syntactically valid but semantically wrong. Missing required fields, invalid reference UIDs, validation rule violations. Do not retry -- fix the payload. * 429 Too Many Requests: rate limited. Retry with exponential backoff + jitter. * Classify before retrying. 429 and 500 are retryable. 401, 403, 404, and 422 are permanent. 412 is retryable but requires a re-fetch first. Retrying permanent errors wastes rate limit quota with zero chance of success. ## Screen: What to Show Outline item Screen instructions Opening (Outline items 1-3) Slide: architecture diagram showing two planes side-by-side. Left: "Delivery Plane" (CDA, GraphQL CDA, Preview API) with arrows to browser/edge/SSR. Right: "Control Plane" (CMA) with arrows to CI/CD, admin scripts, backend services. Code editor: show  api-clients.ts  with the  deliveryClient  and  managementClient  separation. Highlight the different hosts ( cdn.contentstack.io  vs  api.contentstack.io ) and different auth headers ( access\_token  vs  authorization ). Slide: decision framework -- the five-question flowchart. Walk through each question with Veda's storefront as the example.  Regions (Outline items 4-5) Contentstack dashboard: navigate to Settings > Stack to show the region indicator. Slide: regions table showing AWS NA, AWS EU, Azure NA, Azure EU, GCP NA with their CDA and CMA base URLs. Highlight the  .io  vs  .com  TLD difference for AWS NA. Terminal: run the  curl  diagnostic -- hit  cdn.contentstack.io  and  eu-cdn.contentstack.com  with the same credentials, show one returns 200 and the other returns 401. Code editor: show SDK region configuration with  Contentstack.Region.EU  and the  @timbenniks/contentstack-endpoints  helper.  REST vs GraphQL (Outline items 6-7) Postman or terminal: execute the REST query for blog posts with  include\[\]=author . Show the full response payload with all fields. GraphQL playground or Postman: execute the equivalent GraphQL query requesting only  title ,  url , and author  title  +  bio . Show the trimmed response. Split screen: place both response payloads side-by-side. Highlight the size difference. Code editor: show the GraphQL  Connection  pattern for references ( authorConnection { edges { node { ... on Author { title } } } } ).  Authentication (Outline items 8-9) Contentstack dashboard: Settings > Tokens. Create a delivery token -- show the environment scope. Create a management token -- show the stack-level permissions. Code editor: show the  getReadHeaders()  helper that returns different headers for  "published"  vs  "preview"  modes, plus the  managementHeaders  constant. Highlight the comment: "managementHeaders never leaves trusted server code." Terminal: make a CDA request with a delivery token (succeeds). Make the same request with a management token against CDA (fails or returns differently). Show the boundary.  Rate Limits and Errors (Outline items 10-11) Code editor: show the  resilientFetch  function with error classification ( classifyError ), exponential backoff calculation, and rate limit header logging. Terminal: trigger a 429 intentionally (rapid-fire CMA requests in a loop). Show the  X-RateLimit-Remaining  header counting down to zero, then the 429 response. Slide: error code reference table -- status code, retryable yes/no, what to do. Keep it on screen while walking through each code. Terminal: show a 401 from a region mismatch, a 422 from a malformed payload, and a 404 from a wrong content type UID. For each, show the JSON error body and explain the fix. ## Veda Scenario Thread Veda is a fashion and lifestyle brand building a headless storefront on Contentstack. Use Veda throughout this video to ground every concept in a real project context. * **Two APIs, two jobs:** Veda's Next.js storefront fetches product pages, collection listings, and editorial content through CDA. A separate backend service handles content migrations, automated tagging, and bulk publishing through CMA. Two codebases, two token types, two reliability contracts. * **Decision framework:** walk through the five questions using Veda's "Related Products" strip. Intent: render published products for shoppers (CDA). Data state: published (CDA). Runtime: edge-rendered storefront (no management creds). Token: delivery token safe in browser. Blast radius of misuse: reads only, no data integrity risk. * **Regions:** Veda's primary market is Europe. Their stack is on AWS EU. Every base URL uses the eu- prefix. When an American contractor onboarded and copied cdn.contentstack.io from a tutorial, requests returned empty results with no error message -- a classic region mismatch. * **REST vs GraphQL:** Veda uses REST via the SDK for standard product detail pages (simple, cacheable, SDK handles includes). For the homepage -- which pulls hero content, featured collections, editorial picks, and navigation items from four content types -- they use a single GraphQL query to avoid four separate REST calls. * **Authentication:** Veda's delivery token is scoped to the production environment and is safe in the Next.js client bundle. The management token lives only in a backend service that runs nightly content sync jobs. When the marketing team asked for a "quick admin panel" in the storefront, the engineering team said no -- management tokens do not belong in client-facing code. * **Rate limits:** during Black Friday content preparation, Veda's ops team ran a migration script that bulk-published 2,000 product entries. At CMA's 10 req/s limit, the script started hitting 429s after the first batch. They added exponential backoff with jitter, read X-RateLimit-Remaining to throttle proactively, and completed the publish in 8 minutes instead of crashing in a retry storm. * **Error codes:** a junior developer on Veda's team got a 404 when querying a product entry that definitely existed. The UID was correct, the token was correct -- but the SDK was configured for Contentstack.Region.US instead of Contentstack.Region.EU. The entry did not exist in the NA region. Region mismatch masquerading as a missing resource. ## Transitions Item 1 to 2: "Now that you see these are two separate planes, the question becomes: how do you decide which one to use for any given integration?" Item 2 to 3: "The decision framework handles most cases cleanly, but there is one nuance worth calling out -- what about content that is not yet published?" Item 3 to 4: "Once you know which API plane you need, the next thing to get right is the base URL -- and that depends entirely on your stack's region." Item 4 to 5: "Knowing the regions exist is one thing -- let me show you exactly where to find yours and how to configure it." Item 5 to 6: "With the right endpoint locked in, you have one more architectural choice: do you query with REST or GraphQL?" Item 6 to 7: "Theory is useful, but seeing both side-by-side makes the tradeoff concrete." Item 7 to 8: "You have picked your API plane, your region, and your query surface -- now you need the credentials to actually make the call." Item 8 to 9: "Understanding token types is half the job. The other half is making sure each token only exists where it belongs." Item 9 to 10: "Your tokens are in place and your queries are running -- but what happens when you send too many too fast?" Item 10 to 11: "Rate limits are one kind of error. Let me walk you through every error code you are likely to see and exactly what each one means for your code." Closing to Video 6: "You now have the full picture of Contentstack's API surface: which plane to use, which region to target, which query format to choose, how to authenticate, and how to handle errors. In Video 6, we will put this into practice with the SDK, CLI tooling, and developer workflow patterns." ## Common Mistakes to Call Out 1. **Using CMA GET endpoints for frontend delivery.** It works locally. It returns data. But you are shipping a management token to the browser, getting no CDN caching, and mixing your reliability planes. Classify endpoints by intent, not by HTTP verb. 2. **Hardcoding base URLs instead of using SDK region constants.** Copy-pasting cdn.contentstack.io from a tutorial when your stack is on EU or Azure. The SDK has Contentstack.Region.EU for a reason -- use it. 3. **Confusing** **.io** **and** **.com** **TLDs. AWS NA uses** **contentstack.io****.** Every other region uses contentstack.com. Changing the prefix but keeping the wrong TLD produces silent failures. 4. **Choosing GraphQL to avoid learning REST query syntax.** GraphQL is not "better REST." If your queries are simple and the SDK handles them well, GraphQL adds complexity without benefit. 5. **Assuming GraphQL supports mutations.** GraphQL CDA is read-only. All writes, workflow changes, and admin actions require the REST-based CMA. Teams that architect write operations against GraphQL hit a wall. 6. **Shipping management tokens in client-side code.** This is not a documentation issue -- it is an architecture issue. Management credentials belong only in trusted backends. If a token ends up in the browser, the blast radius is your entire stack. 7. **Sharing one management token across many services.** If revoking that token breaks five unrelated systems, your security boundary is too broad. One credential per service responsibility. 8. **Retrying all errors uniformly.** Wrapping every API call in a generic retry loop that treats 422 and 429 identically. Invalid payloads (422) will never succeed on retry -- you are just burning rate limit quota. 9. **No jitter in retry backoff.** Fixed-delay retries across concurrent clients create a thundering herd. Every retry implementation must include randomness. 10. **Ignoring** **X-RateLimit-Remaining** **until you get a 429.** Read the header on every response. Throttle proactively before hitting the ceiling, not reactively after crashing through it. 11. **Assuming a 404 means the resource does not exist.** It might mean you are querying the wrong region. The API does not tell you "this resource exists in a different region" -- it just says "not found." ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 5 — API Architecture, Authentication, and Query Surface Choice** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 21 — Video Production Plan : Video 6 — Fetching and Rendering Content with the SDK #### Lesson text # Video 6 — Fetching and Rendering Content with the SDK Attribute Details Course 3 (APIs and Developer Tooling), Module 3.2 (lessons 1-2) Covers Lessons 3.2.1, 3.2.2 Priority Critical Length 15-22 min Format Screencast (code editor + browser) Status Not started ## Why This Video Matters This is the moment the platform becomes real for developers. Learners watch content move from Contentstack into application code. ## Outline 1. SDK initialization: setting up the JavaScript SDK with stack API key, delivery token, and environment 2. Stack client setup and configuration 3. Fetching entries by content type, UID, and URL 4. Query chaining: conditions, sorting, pagination 5. Live-code a few common queries against the Veda stack 6. References and includes: how to resolve referenced entries in a single query (include depth levels) 7. Localization in queries: fetching locale-specific content, fallback behavior 8. Rendering a realistic response shape in the frontend ## Key Lines "This is the moment the platform becomes real for developers." "You are not just fetching content. You are shaping how the app consumes it." "Understanding the response object makes everything else easier." ## Detailed Talking Points ### 1\. SDK initialization: setting up the JavaScript SDK with stack API key, delivery token, and environment * Install @contentstack/delivery-sdk (not the legacy contentstack package). This is the modern, TypeScript-first SDK with tree-shaking support. * Call Contentstack.stack() with four required values: apiKey, deliveryToken, environment, and region. * Show where each credential lives in the dashboard: API key in Settings > Stack, delivery token in Settings > Tokens > Delivery Tokens. * Emphasize that region must match the data center where the stack was created. Wrong region gives empty results or 401 with zero hint about the actual cause. * Delivery tokens are scoped to a specific environment. Token for staging does not work when environment is set to production. * The SDK does not throw on initialization if credentials are empty strings. The error surfaces on the first query as a cryptic 401 or 412. Validate at startup. * Optional: pass branch if the stack uses branches. Without it, the SDK queries the main branch. ### 2\. Stack client setup and configuration * Walk through a real stack instance in code. Show the import: import Contentstack from "@contentstack/delivery-sdk". * Show environment variables pattern: process.env.NEXT\_PUBLIC\_CONTENTSTACK\_API\_KEY, etc. * Demonstrate Contentstack.Region.US vs Contentstack.Region.EU -- these are built-in constants, not arbitrary strings. * Mention branch configuration for teams doing parallel content development: branch: "feature-digital-dawn-v2". * Stress that this stack instance is reused across the entire app. You initialize once, query many times. ### 3\. Fetching entries by content type, UID, and URL * Show stack.contentType("product").entry().query().find() -- this fetches all entries of a content type. * Show stack.contentType("product").entry("blt\_matrix\_link\_001").fetch() -- single entry by UID. Returns the entry directly, not wrapped in an array. * Show fetching by URL with .equalTo("url", "/products/digital-dawn/matrix-link-bracelet") -- this drives most page rendering in frontend frameworks. * Explain the difference: find() returns { entries: \[\], count: number }, while fetch() returns the entry object directly. * Under the hood, these map to GET /v3/content\_types/product/entries and GET /v3/content\_types/product/entries/{uid}. * Fetching by UID is faster and more cache-friendly than querying with a filter when you already have the UID. ### 4\. Query chaining: conditions, sorting, pagination * Show .equalTo("category", "blt\_earrings\_category\_001") for simple equality filters. * Show .where("price", QueryOperation.IS\_GREATER\_THAN, 100) for comparison operators. Import QueryOperation from the SDK. * List available operators: IS\_LESS\_THAN, IS\_GREATER\_THAN, EQUALS, INCLUDES -- these map to Contentstack's $gt, $lt, $in, $nin, etc. * Pagination: .limit(10).skip(0) for page 1, .limit(10).skip(10) for page 2. Default max is 100 entries per request. * Sorting: .orderByAscending("price") or .orderByDescending("created\_at"). * Stress that all these chain before .find(). The query is built, then executed. ### 5\. Live-code a few common queries against the Veda stack * Query 1: All products, sorted by price ascending. Show the response shape in the console. * Query 2: Products above $200 using .where("price", QueryOperation.IS\_GREATER\_THAN, 200). * Query 3: Paginated product listing -- first 5 products, then next 5. Show skip and limit in action. * Query 4: Products filtered by URL slug for a single product detail page. * Keep each query short. Type it live, run it, show the console output. No slides. * Point out system fields in the response: uid, created\_at, updated\_at, locale, \_version. ### 6\. References and includes: how to resolve referenced entries in a single query (include depth levels) * Without includeReference(), reference fields return UID stubs: { uid: "blt...", \_content\_type\_uid: "product\_line" }. You get the pointer, not the data. * Chain .includeReference("product\_line") to resolve references inline. Multiple fields: chain multiple .includeReference() calls. * The parameter takes the reference _field UID_ on the parent content type, not the content type UID of the target. This trips people up. * Depth levels via dot notation: .includeReference("product\_line.products") resolves two levels deep. * Performance: depth 1 is standard and fast. Depth 2 is acceptable. Depth 3+ risks payload bloat and increased latency. Only include what the current view renders. * Show the include\_all shorthand via .addParams({ include\_all: true, include\_all\_depth: 2 }) -- useful for page-level queries but less efficient for listing pages. * Anti-pattern: including everything "just in case." Each unnecessary include adds latency and bytes. ### 7\. Localization in queries: fetching locale-specific content, fallback behavior * Add .locale("fr-fr") to any query to fetch content in a specific locale. * Without include\_fallback, untranslated fields come back as empty or null. Visitors see blank content. * Chain .includeFallback() to walk the fallback chain: fr-ca -> fr -> en-us (master locale). * When references and locale are combined, referenced entries resolve in the same locale automatically. No need to specify locale per reference. * Gotcha: if a referenced entry does not exist in the requested locale and has no fallback, it may be excluded entirely from the response. Test locale coverage across content types. * Show publish\_details on the entry to determine which locale the content actually came from. ### 8\. Rendering a realistic response shape in the frontend * Map the SDK response to component props. Show a Product component receiving title, price, short\_description, product\_line\[0\].title. * Handle null fields defensively. Not every entry has every field filled in, especially with partial localization. * Use TypeScript generics on find() and fetch(): query.find() gives typed result.entries as Product\[\]. * Define types matching the content type schema. Reference the kickstart-veda lib/types.ts as a real-world example. * Show the before/after: untyped response with any vs typed response with autocomplete and compile-time checks. * Stress that understanding the response object makes everything else easier. Once you know the shape, rendering is straightforward. ## Screen: What to Show Timestamp Screen content 0:00-2:00 VS Code with empty file. Type the npm install command, then the SDK import and Contentstack.stack() call. Terminal split showing install output. 2:00-3:30 Contentstack dashboard: Settings > Stack (show API key), Settings > Tokens > Delivery Tokens (show token + environment scope), Settings > Stack Information (show region). 3:30-5:00 Back to VS Code. Complete the stack initialization with env vars. Add a simple contentType("product").entry().query().find() call. Run it. Show console output with entry array. 5:00-7:00 Live-code .entry("blt\_matrix\_link\_001").fetch() for single entry. Then .equalTo("url", "/products/digital-dawn/matrix-link-bracelet") for URL-based fetch. Run both, compare output shapes. 7:00-9:00 Build query chains live: .where("price", QueryOperation.IS\_GREATER\_THAN, 200), then add .orderByAscending("price"), then .limit(5).skip(0). Run after each addition so viewers see the query narrowing. 9:00-11:00 Show a product response with unresolved reference stubs. Add .includeReference("product\_line").includeReference("category"). Run again. Highlight the before/after difference in the console -- stubs vs full objects. 11:00-12:30 Show nested include: .includeReference("product\_line.products"). Run it. Show the expanded payload. Briefly open browser DevTools Network tab to show response size difference. 12:30-14:00 Add .locale("fr-fr") to the query. Run it. Show translated fields. Remove .includeFallback() and show blank fields. Add it back. Show fallback content appearing. 14:00-16:00 Switch to a React component file. Map the response to props: product.title, product.price, product.product\_line\[0\]?.title. Show null-safe access patterns. 16:00-18:00 Add TypeScript generics: query.find(). Show autocomplete kicking in. Show a type definition file matching the content type schema. 18:00-end Browser showing rendered Veda product page with data flowing from Contentstack. Zoom into the product card showing title, price, product line name, category. ## Veda Scenario Thread Veda: The Revival Collection (jewelry e-commerce) runs through this entire video as the practical context. * **Opening:** "We have a Veda jewelry catalog with products, product lines, and categories. Let us connect to it." Initialize the SDK with Veda stack credentials. * **First queries:** Fetch all Veda products. Then filter to products over $200 -- show items like the Matrix Link Bracelet ($295) appearing in results. * **Single entry:** Fetch the Matrix Link Bracelet by UID (blt\_matrix\_link\_001) and by URL (/products/digital-dawn/matrix-link-bracelet). Show both paths to the same entry. * **References:** Show the Matrix Link Bracelet with unresolved product\_line and category stubs. "Right now we know this product belongs to _something_, but we do not know what." Add includeReference() calls. "Now we see Digital Dawn and Bracelets." * **Nested references:** Include product\_line.products to show other products in the Digital Dawn line (Pixel Stud Earrings, etc.). Talk about when this depth is worth the payload cost. * **Localization:** Switch the query to fr-fr. Show the Matrix Link Bracelet with French title ("Bracelet Maillon Matrice") where translated, English fallback where not. Show the gap without includeFallback(). * **Rendering:** Build a simple Veda product card component. Map product.title, product.price, product.product\_line\[0\].title, product.category\[0\].title to the card layout. Show it rendering in the browser. * **Closing:** "This is how Veda goes from CMS entries to a rendered product page. Every query pattern we covered -- filtering, pagination, references, localization -- is something you will use building pages like this." ## Transitions 1. **Intro to SDK initialization:** "Before you can render anything, you need a connection to your stack. Let us set one up." 2. **SDK init to stack client setup:** "The stack instance is created. Now let us look at what configuration options matter and where to find each credential." 3. **Stack client to fetching entries:** "Configuration is done. Time to fetch actual content." 4. **Fetching entries to query chaining:** "Fetching everything is a start, but real apps need filters, sorting, and pagination." 5. **Query chaining to live coding:** "Enough theory. Let us write these queries against real Veda data and see what comes back." 6. **Live coding to references and includes:** "Our queries return products, but the product line and category fields are just UID stubs. Let us fix that." 7. **References to localization:** "References are resolved. Now what happens when your site serves content in multiple languages?" 8. **Localization to rendering:** "We can fetch content in any locale with fallbacks. The last step is mapping this data to components." 9. **Closing to Video 7:** "You now know how to fetch, filter, resolve, and render content from Contentstack. In the next video, we tackle Live Preview -- seeing content changes in real time before they are published." ## Common Mistakes to Call Out * **Wrong region, silent failure:** Initializing with Region.US when the stack is in EU. The SDK does not tell you the region is wrong. You get empty results or a 401. Always verify in Settings > Stack Information. * **Environment/token mismatch:** The delivery token is scoped to one environment. Using a staging token with environment: "production" fails silently or returns auth errors. * **Empty credential strings:** The SDK accepts empty strings at init time without throwing. The first query fails with a cryptic 401 or 412. Validate credentials before the first query. * **Using content type UID instead of field UID in** **includeReference()****:** include\[\]=categories when the field UID is category returns 200 but references stay as stubs. The parameter is the _field UID_ on the parent, not the target content type UID. * **Forgetting** **includeFallback()** **on partially localized stacks:** Without it, untranslated fields return empty. Visitors see blank sections instead of parent-locale content. * **Over-including nested references:** Including product\_line.products.category (three levels deep) balloons the response payload. Only include what the current view actually renders. * **Assuming all referenced entries exist in all locales:** If categories are only in English and you request ja-jp without fallback, categories come back empty or missing entirely. * **Not handling null fields in rendering:** Partial localization and optional fields mean any field can be null. Always use null-safe access (product.product\_line\[0\]?.title) or default values. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 6 — Fetching and Rendering Content with the SDK** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 22 — Video Production Plan : Video 7 — Performance, Images, Environments, and CLI Migrations #### Lesson text # Video 7 — Performance, Images, Environments, and CLI Migrations Attribute Details Course 3 (APIs and Developer Tooling), Module 3.2 (lessons 3-4) + Module 3.3 Covers Lessons 3.2.3, 3.2.4, 3.3.1, 3.3.2, 3.3.3 Priority Core Length 20-28 min Format Screencast (terminal + Contentstack UI + code editor) Status Not started ## Why This Video Matters This turns Contentstack from a simple content source into an operationally mature implementation. A working integration is not the same thing as a production-ready integration. ## Outline 1. Image Delivery API: URL-based transformations (resize, crop, format conversion, quality) 2. Show image transformation parameters and their impact on page performance 3. Responsive image strategies 4. Caching strategies: CDN behavior, cache invalidation on publish, stale-while-revalidate patterns 5. Frontend rendering strategies: SSG (build-time), SSR (request-time), ISR (incremental), CSR (client-side) — when each makes sense 6. Environments explained: development, staging, production — each with its own publish queue and delivery token 7. Content promotion: publishing to dev first, then staging, then production 8. Aligning CMS environments with CI/CD pipelines 9. Contentstack CLI (csdx): installation, authentication, key commands 10. Live demo: export a stack, import into another, run a content type migration 11. Migration scripts: programmatically creating and modifying content types 12. When to use CLI vs UI vs Management API ## Key Lines "A working integration is not the same thing as a production-ready integration." "Environment strategy is where content delivery and deployment reality meet." "The CLI is where repeatability starts to replace manual effort." ## Detailed Talking Points ### 1\. Image Delivery API: URL-based transformations * Contentstack serves every uploaded asset through its Image Delivery CDN — the URL you get back from the Delivery API is already on the CDN. * Transformations are query parameters appended to the URL: ?width=400, ?height=300, ?format=webp, ?quality=80, ?crop=400,400,x100,y50, ?fit=crop. * No build step, no image processing pipeline, no Lambda function — the CDN handles transformation and caching at the edge. * The ?auto=webp parameter is the easiest win: it inspects the browser's Accept header and serves WebP when supported, falling back automatically. Typical savings: 25-35% payload reduction. * Region matters for the host: NA uses images.contentstack.io, EU uses eu-images.contentstack.com, Azure variants exist too. * Combined parameters in one URL: ?width=800&height=600&fit=crop&format=webp&quality=80 — one request, one cached result. ### 2\. Image transformation parameters and performance impact * Show a before/after: original 4000px product image vs. ?width=800&auto=webp&quality=80. Compare file sizes in the Network tab. * Quality between 70-85 is the sweet spot for product photography. Below 60, compression artifacts become visible. * The fit parameter controls behavior when both width and height are set: bounds scales to fit within dimensions, crop fills exact dimensions and trims overflow. * trim=20,20,20,20 removes uniform whitespace — useful for product catalog images with inconsistent borders. * The key principle: always match ?width= to the rendered size. A 4000px image displayed at 800px wastes bandwidth and tanks your LCP score. ### 3\. Responsive image strategies * Use srcset to give the browser multiple width options: 400w, 800w, 1200w, 1600w — all generated by varying the ?width= parameter on the same base URL. * Pair srcset with sizes to tell the browser how wide the image renders at each breakpoint: (max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw. * Build a buildImageUrl() and buildSrcSet() utility function rather than constructing URLs manually — avoids string concatenation bugs and enforces consistent quality/format settings. * Art direction with different crops: use ?crop= or ?fit=crop with different aspect ratios for mobile vs. desktop hero images. * Always set explicit width and height attributes on elements to prevent CLS (Cumulative Layout Shift). * Use loading="lazy" for below-fold images, omit it (or use loading="eager") for above-fold hero images. * Preload the LCP image with . ### 4\. Caching strategies * Contentstack's CDN invalidates on publish — when an editor publishes or unpublishes, stale cache entries are evicted globally within seconds. * Between publishes, identical API calls resolve at the CDN edge without hitting origin servers. * Draft saves do not affect the delivery cache. Only the publish action triggers invalidation. * Contentstack sends Cache-Control: public, max-age=0, must-revalidate — the CDN is the source of truth, not the browser cache. * If you add your own caching layer (Redis, edge cache, in-memory), you must add webhook-driven invalidation. Contentstack only purges its own CDN, not yours. * The stale-while-revalidate pattern: serve cached content immediately, fetch fresh content in the background. Ideal for content that updates periodically but where a few seconds of staleness is acceptable. ### 5\. Frontend rendering strategies * SSG (Static Site Generation): pages built at build time, served from static CDN. Fastest possible load. Content only updates on rebuild. Best for: stable pages, reference content, documentation. * SSR (Server-Side Rendering): page generated on every request. Always fresh. Adds latency (API call + render). Best for: personalized content, search results, breaking news. * ISR (Incremental Static Regeneration): hybrid — static pages that regenerate after a time interval or on-demand. Combine revalidate = 60 with webhook-triggered revalidation for best of both worlds. * CSR (Client-Side Rendering): SPA pattern, content fetched in the browser after initial load. No SEO benefit from CMS content. Best for: authenticated dashboards, interactive tools. * For Veda: homepage gets ISR with 30s revalidation, product pages get ISR with 60s, category pages get SSG with webhook-triggered rebuilds, search results get SSR. * Webhook-triggered rebuilds close the loop: editor publishes → Contentstack fires webhook → hosting platform triggers rebuild → new static site deploys in 30-120 seconds. ### 6\. Environments explained * An environment in Contentstack is a deployment target, not a code branch. This trips up developers from git-centric workflows. * Typical setup: development (dev integration testing), staging (QA and stakeholder review), production (live customer-facing). * Each environment gets its own delivery token. Your production frontend uses a production-scoped token. Staging uses a different token. * Token isolation limits blast radius — if a staging token leaks, production content is unaffected. * Each environment has independent published content state. Publishing to staging does not make content available in production. * Environments have a Base URL (the frontend that consumes content) and an optional Preview URL for Live Preview. ### 7\. Content promotion flow * Promotion strategy mirrors application deployment: dev → staging → production. * Editor creates entry, publishes to development. Developer verifies rendering. Editor promotes to staging for QA review. Senior editor publishes to production. * Each publish action is explicit and auditable. Content does not drift between environments without intentional action. * Publish rules restrict which roles can publish where: Content Authors to dev only, Content Managers to dev and staging, Senior Editors to production. * Publish assets before the entries that reference them to avoid broken references on the target environment. * The publish queue processes requests asynchronously — clicking Publish does not guarantee instant CDN availability. Monitor the queue for large bulk operations. ### 8\. Aligning CMS environments with CI/CD pipelines * Content publishes and code deploys operate on independent timelines — this independence is a feature, not a flaw, but it creates a coordination problem. * The primary integration point: webhooks. Contentstack fires HTTP webhooks on publish events. Point them at your build hook (Vercel deploy hook, Netlify build hook, GitHub Actions dispatch). * Filter webhooks by environment and content type. Development publishes should not trigger production builds. Metadata-only content types should not trigger rebuilds. * Content-as-code: export content type schemas with the CLI, commit them to version control. Add a CI step that detects schema drift between Contentstack and your committed definitions. * Manage delivery tokens as CI/CD secrets. Each CI/CD context (preview, staging, production) injects the correct token via environment variables. * Rollback order matters: revert code first (restore the frontend that expects the old schema), then republish previous content versions. ### 9\. Contentstack CLI: installation, authentication, key commands * Install globally: npm install -g @contentstack/cli. Verify with csdx --version. * Interactive login: csdx auth:login opens browser-based OAuth. Good for local dev, not for CI/CD. * Token-based auth for automation: csdx auth:tokens:add --alias "my-stack" --stack-api-key "..." --management --token "..." --yes. * Token aliases simplify repeated operations — reference \--alias my-stack instead of passing raw keys every time. * List stored tokens: csdx auth:tokens. Remove a token: csdx auth:tokens:remove --alias "my-stack". * The CLI uses a plugin architecture. Core commands cover stack management, content export/import, and authentication. ### 10\. Live demo: export, import, and migration * Export a full stack: csdx cm:stacks:export --alias "source" --data-dir ./export-data. * Export specific modules: \--module content-types --module global-fields --module assets. * Show the exported directory structure: JSON files organized by module — content-types/product.json, entries/product/en-us/, assets/. * Import into target: csdx cm:stacks:import --alias "target" --data-dir ./export-data. * Use \--replace-existing to overwrite existing content types during import. * Always back up before importing to production: csdx cm:stacks:export --alias "prod" --data-dir ./backup/$(date +%Y%m%d). * Seed a new stack from a template: csdx cm:stacks:seed --repo "contentstack/stack-starter-app". ### 11\. Migration scripts * For changes beyond simple export/import — renaming fields, transforming data, backfilling values — use programmatic scripts with the Content Management API. * Example: backfill a description\_word\_count field across all Veda product entries. Fetch entries via CMA, calculate the value, update each entry. * Migration scripts give you full control over transformation logic, error handling, and execution order. * Wrap CLI export/import in CI/CD pipelines (GitHub Actions workflow) for automated content model sync across multiple stacks. * Use workflow\_dispatch with matrix strategy to fan out imports across brand stacks in parallel. ### 12\. When to use CLI vs UI vs Management API * UI: one-off content type changes, small-scale content edits, exploratory work. Fast feedback, no scripting needed. * CLI (csdx): repeatable operations across stacks — export/import, seeding, bulk operations. Scriptable, auditable, belongs in CI/CD. * Management API (CMA): programmatic migrations, custom tooling, data transformations, backfills. Full control, requires code. * Rule of thumb: if you are doing it once, use the UI. If you are doing it more than once, use the CLI. If you need transformation logic, use the CMA. * Treat content migrations like database migrations: plan them, test against non-production, back up before production, log everything. ## Screen: What to Show Outline Item What to Show on Screen 1\. Image Delivery API Browser with a Contentstack asset URL. Append ?width=400&format=webp&quality=80 live in the address bar. Show the image changing/resizing in real time. 2\. Transformation impact Chrome DevTools Network tab. Load a product page with original images, then with optimized URLs. Compare file sizes side by side (highlight the KB reduction). 3\. Responsive images Code editor showing a buildImageUrl() and buildSrcSet() utility function. Then the rendered HTML element with srcset in Elements panel. Use Chrome responsive mode to show different image sizes loading at different breakpoints. 4\. Caching Chrome DevTools Network tab — show a Contentstack API response with Cache-Control headers. Then show a publish action in Contentstack UI and the subsequent fresh response. Optionally show a simple stale-while-revalidate code snippet. 5\. Rendering strategies Side-by-side diagram or slide: SSG vs SSR vs ISR vs CSR with arrows showing when the API call happens (build time, request time, background, client). Show Next.js code with revalidate = 60 and a revalidation API route. 6\. Environments Contentstack dashboard: Settings > Environments. Show the three environments (development, staging, production) with their Base URLs. Then Settings > Tokens showing three delivery tokens, one per environment. 7\. Content promotion Contentstack entry editor. Click Publish, show the environment selector. Publish to development first, then show the entry in staging (not yet published), then publish to staging. Show the publish queue (Settings > Publish Queue). 8\. CI/CD alignment Code editor: show a webhook handler that filters by environment and content type. Then Contentstack dashboard: Settings > Webhooks configuration. Optionally show a GitHub Actions schema-drift-check workflow YAML. 9\. CLI installation and auth Terminal: npm install -g @contentstack/cli, csdx --version, csdx auth:tokens:add with alias. Show the token list with csdx auth:tokens. 10\. Live demo Terminal: run csdx cm:stacks:export and show the output directory. Open a JSON file in the editor. Run csdx cm:stacks:import against a target stack. Switch to Contentstack UI to verify the imported content types appear. 11\. Migration scripts Code editor: show a TypeScript migration script that uses @contentstack/management to backfill a field. Run it in the terminal with npx tsx scripts/backfill.ts. Show the updated entries in Contentstack UI. 12\. CLI vs UI vs CMA Simple three-column comparison slide or table on screen. No code needed — just a clear visual summary. ## Veda Scenario Thread Veda: The Revival Collection (jewelry e-commerce) runs through this entire video as the practical context. * **Images (items 1-3):** You are optimizing Veda product images. Start with a Matrix Link Bracelet product photo served at full resolution (4000px). Show how appending ?width=800&auto=webp&quality=80 slashes the file size. Build the buildSrcSet() utility for the product card grid — 300w, 600w, 900w breakpoints for the Pixel Stud Earrings, Circuit Collar Necklace, and Data Drop Earrings product cards. Add for the Digital Dawn hero image on the homepage. * **Caching and rendering (items 4-5):** Veda's homepage uses ISR with 30-second revalidation because campaign launches need fast propagation. Product pages use ISR with 60-second revalidation and webhook-triggered on-demand revalidation. Category pages use SSG with webhook-triggered rebuilds. Search results use SSR because query parameters vary per request. Show a webhook handler that triggers a Vercel rebuild only for product, page, and product\_line content types on the production environment. * **Environments (items 6-7):** Veda has three environments: development at dev.veda.example.com, staging at staging.veda.example.com, production at veda.example.com. Walk through publishing a new seasonal collection entry: publish to dev for developer verification, promote to staging for the merchandising team, then production for the customer-facing storefront. Show how publish rules prevent a junior content author from accidentally pushing an unreviewed product to production. * **CI/CD (item 8):** Veda's CI/CD pipeline on Vercel uses environment-specific delivery tokens injected as environment variables. A webhook fires on production publish and triggers a rebuild. The content type schemas are exported and committed to the repo, with a GitHub Actions step that detects schema drift on pull requests. * **CLI and migrations (items 9-12):** Veda is expanding from one brand stack to three brand stacks (Alpha, Beta, Gamma). Use the CLI to export the product and category content types from the Alpha stack, import them into Beta and Gamma. Then run a migration script that backfills a description\_word\_count field across all product entries in all three stacks. Wrap the workflow in a GitHub Actions pipeline with matrix strategy for parallel execution. ## Transitions 1 → 2: "Now that you see how the URL parameters work, let us look at the actual performance impact in the browser." 2 → 3: "Optimizing one image is useful — building a system that optimizes every image across your product catalog is what matters." 3 → 4: "Images are cached at the CDN edge, but what about the API responses that tell you which images to show?" 4 → 5: "Caching controls when data refreshes — rendering strategy controls when pages are built from that data." 5 → 6: "Rendering strategies tie to environments, because each environment serves different content to a different audience." 6 → 7: "Having environments is one thing — having a disciplined flow for moving content through them is another." 7 → 8: "Content promotion aligns with code deployment, and that is where CI/CD integration becomes essential." 8 → 9: "The CI/CD pipeline needs tooling to automate content operations, and that tooling is the Contentstack CLI." 9 → 10: "Let us stop talking about the CLI and start using it." 10 → 11: "Export and import handle structural replication — migration scripts handle data transformation." 11 → 12: "With three tools in your belt — CLI, UI, and Management API — you need to know when to reach for each one." 12 → Video 8: "You now have the operational foundation: optimized images, caching strategy, environment discipline, and CLI automation. In the next video, we bring it all together with Contentstack Launch and a full deployment walkthrough." ## Common Mistakes to Call Out 1. **Serving full-resolution images at display size.** A 4000px image displayed at 800px wastes bandwidth and destroys your LCP score. Always match ?width= to the rendered size. 2. **Skipping** **auto=webp****.** A single query parameter reduces payload by 25-35% with zero effort. There is no reason not to use it. 3. **Missing** **width** **and** **height** **attributes on** **** **elements.** Without them, the browser cannot reserve space before the image loads, causing layout shifts that tank your CLS score. 4. **Adding a caching layer without webhook-driven invalidation.** Contentstack only invalidates its own CDN. If you add Redis, edge cache, or in-memory cache without a purge mechanism, editors publish content that never appears on the site. 5. **Using SSR for everything.** SSR guarantees freshness but wastes resources on pages that rarely change. Product pages, category pages, and documentation should use SSG or ISR. 6. **Confusing environments with branches.** Environments are deployment targets (dev, staging, production). Branches are for parallel content development. Creating an environment called feature-new-checkout is misusing the system. 7. **Publishing directly to production without staging verification.** Skipping staging saves a few minutes and costs hours when broken content, missing references, or layout issues reach customers. 8. **Sharing delivery tokens across environments.** Using the production token in your staging frontend defeats environment isolation. Each frontend deployment must use the token scoped to its corresponding environment. 9. **Publishing entries before their referenced assets.** A product entry referencing an unpublished hero image produces a broken storefront page. Publish assets first. 10. **Running** **\--replace-existing** **imports on production without a backup.** Always export the current state before migrating production: csdx cm:stacks:export --alias "prod" --data-dir ./backup/$(date +%Y%m%d). 11. **N+1 query patterns in template loops.** A loop over 20 products that fetches product line data per iteration makes 21 API calls instead of 1. Use includeReference() to resolve references in the original query. 12. **Hardcoding stack credentials in migration scripts.** Use environment variables or the CLI's token alias system. Never commit API keys or management tokens to version control. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 7 — Performance, Images, Environments, and CLI Migrations** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 23 — Video Production Plan : Video 8 — Live Preview Architecture and Preview Routing #### Lesson text # Video 8 — Live Preview Architecture and Preview Routing Attribute Details Course 4 (Preview, Visual Builder, and Releases), Module 4.1 (lessons 1-3) Covers Lessons 4.1.1, 4.1.2, 4.1.3 Priority Critical Length 18-25 min Format Screencast (code editor + Contentstack UI side-by-side) Status Not started ## Why This Video Matters Preview is one of the places where a visual explanation helps much more than text alone. Headless architectures do not give you preview for free — it requires deliberate implementation. ## Outline 1. Why Live Preview matters: editors need to see changes before publishing; without it, they fly blind 2. The two-delivery-plane mental model: preview token vs delivery token 3. Requirements: what your frontend needs to support (SDK initialization with live preview config, preview token, host URL) 4. Draft vs published routing: how to serve draft content in preview mode and published content in production 5. Show the configuration in Contentstack settings and the corresponding frontend code 6. SSR preview pattern: server fetches draft content on each request 7. CSR preview pattern: client-side SDK listens for changes and re-renders in real time 8. onEntryChange, edit tags, and preview transport 9. Walk through a working Live Preview implementation step by step 10. Common failure modes: CORS issues, wrong environment tokens, caching interfering with draft content ## Key Lines "Headless architectures do not give you preview for free." "Preview is a product capability, not a side feature." "If preview behavior is inconsistent, editorial trust erodes quickly." ## Detailed Talking Points ### 1\. Why Live Preview matters * Headless CMS architectures do not provide preview out of the box. Preview is an architecture concern, not a UI toggle. * Without preview, editors "fly blind" -- they publish content hoping it looks right, or they ask developers to check for them. Both are slow and error-prone. * Preview is a correctness system. When an editor asks "is this page ready?", they are asking a systems question: can I trust what I see before I hit publish? * Unreliable preview leads to two failure modes: teams publish too cautiously (slow velocity) or too optimistically (broken pages in production). * Frame preview as a product capability, not a nice-to-have. Treat preview correctness as a release criterion. ### 2\. The two-delivery-plane mental model * Split content delivery into two planes: the published plane (optimized for live user traffic, CDN-cached, Delivery Token) and the preview plane (optimized for draft validation, no caching, Preview Token). * If you treat preview as "published plus a flag," you get inconsistent results. Preview has different host routing, request context, and caching expectations. * Published traffic goes to cdn.contentstack.io (or your region's CDA host). Preview traffic goes to rest-preview.contentstack.com (or your region's preview host). * Both tokens are scoped to an environment. The difference: the Delivery Token only returns published entries. The Preview Token returns the latest saved version of every entry, regardless of publish state. * The Preview Token does not bypass environments -- it bypasses the publish gate. An entry does not need to be published for the Preview Token to return it. ### 3\. Requirements: SDK initialization and preview config * Three things your frontend needs: the Live Preview SDK (@contentstack/live-preview-utils), a Preview Token, and the correct preview host URL for your region. * Initialize the Delivery SDK with live\_preview config: enable: true, preview\_token, and host pointing to your region's preview endpoint. * Initialize ContentstackLivePreview.init() separately with ssr: true or ssr: false (matching your rendering model), mode: "builder", stackSdk, stackDetails, and clientUrlParams.host pointing to your region's Contentstack app URL. * The clientUrlParams.host must match the Contentstack web app for your region (e.g., eu-app.contentstack.com for AWS EU). Getting this wrong causes silent failures. * Use @timbenniks/contentstack-endpoints to resolve correct base URLs for any region string -- avoids hardcoding the wrong host. * The editButton config with exclude: \["outsideLivePreviewPortal"\] ensures the floating edit button only appears inside the Contentstack preview iframe. ### 4\. Draft vs published routing * Two hosting approaches: separate preview host (recommended) or single host with mode switching. * Separate host: www.example.com runs with Delivery Token, preview.example.com runs with Preview Token. Same codebase, different env vars. Complete isolation. * Single host with mode switching: detect preview mode via URL param (?live\_preview), cookie, or header. Cheaper infrastructure but riskier -- a bug in mode-switching logic could expose draft content to production visitors. * Preview URL structure must mirror production URL structure exactly. If production serves /blog/q3-report, preview must serve /blog/q3-report at the same path. Otherwise editors land on 404s. * In Contentstack, configure the preview base URL under Settings > Live Preview. The CMS constructs preview URLs by combining this base URL with the entry's URL path. ### 5\. Configuration walkthrough (Contentstack settings + frontend code) * Show Settings > Tokens: where to create Preview Token and Delivery Token. * Show Settings > Live Preview: where to set the preview URL base and enable Live Preview for the stack. * Show the .env.production vs .env.preview files side by side: same API key, same environment, different tokens and PREVIEW=true/false flag. * Show the SDK initialization code: how the live\_preview block conditionally enables preview based on the env var. * Emphasize: both deployments share the same Git repository. The only difference is environment variables injected at build/deploy time. ### 6\. SSR preview pattern * Server fetches draft content on each request using the Preview Token. The server renders HTML and sends it to the browser. * The Live Preview SDK initializes on the client with ssr: true. When the editor modifies content, the SDK triggers a page refresh via router.refresh() (Next.js App Router) or window.location.reload(). * router.refresh() is strongly preferred: it re-runs server components without a full page reload, preserving scroll position and client state. * SSR preview is structurally simpler -- no client-side data management. The trade-off is latency: each update requires a server round-trip (typically 200-500ms). * Critical: caching must be explicitly disabled for preview requests. In Next.js App Router, fetch() is cached by default. Set cache: "no-store" or next: { revalidate: 0 } for preview fetches, or editors will see stale content. ### 7\. CSR preview pattern * The browser fetches content directly from Contentstack and renders it in the DOM. Updates are instant and data-driven. * Initialize the SDK with ssr: false. Register ContentstackLivePreview.onEntryChange(callback) -- the callback fires every time the editor modifies a field. * When onEntryChange fires, the SDK has already intercepted the Delivery SDK instance. The re-fetch returns real-time draft data from the postMessage payload -- no network call. The component re-renders instantly. * CSR preview gives the best editor experience: sub-second updates, no page flicker, no scroll position loss. * For hybrid pages (SSR page shell + CSR interactive components), keep SSR-fetched fields on the server path and CSR-fetched fields on the client path. Never mix data sources for the same field -- it creates synchronization bugs where server HTML and client updates disagree. ### 8\. onEntryChange, edit tags, and preview transport * onEntryChange is the primary hook for responding to Live Preview updates. Its behavior depends on the ssr flag. * With ssr: false: callback gets updated data instantly from the postMessage payload. No network round-trip. * With ssr: true: callback triggers a page refresh so the server re-fetches with the updated live\_preview hash. * Edit tags are data-cslp attributes on DOM elements. Format: {content\_type\_uid}.{entry\_uid}.{locale}.{field\_path}. They map rendered content to CMS fields for field-level highlighting and in-place editing. * The postMessage bridge handles all communication between the Contentstack entry editor (parent window) and your app (iframe): handshake, entry changes, hash updates, and navigation events. * You never implement postMessage handling yourself -- the SDK manages it. But knowing it exists explains why Live Preview requires an iframe context and why CORS can block it. ### 9\. Walk through a working implementation step by step * Start from zero: create tokens, configure Live Preview settings, set up env vars, initialize SDKs. * Show the full request flow: editor opens Live Preview, CMS loads preview URL in iframe, SDK detects iframe context, SDK intercepts API calls and redirects to preview host with Preview Token. * Demonstrate a content change: editor types a new headline, postMessage fires, onEntryChange triggers, page updates (instant for CSR, server round-trip for SSR). * Show the live\_preview hash in action: without the hash, preview API returns last saved draft. With the hash, it returns real-time editing state including unsaved changes. * Show edit tags lighting up on hover: the data-cslp attributes enable field-level highlighting so editors can see exactly which DOM element maps to which CMS field. ### 10\. Common failure modes * CORS issues: the Contentstack app and your preview deployment are on different origins. If your server blocks cross-origin iframe embedding or postMessage, Live Preview silently fails. Check X-Frame-Options and CSP headers. * Wrong environment tokens: using a Delivery Token in the preview deployment means editors only see published content. This often goes unnoticed during setup because testing happens with already-published entries. The bug surfaces when an editor creates a brand-new entry and preview shows a 404. * Caching interfering with draft content: CDN caching preview responses, browser caching from a previous production visit, or Next.js fetch cache serving stale data. All three produce the same symptom: editor saves changes, refreshes, sees old content. * Missing or wrong preview host configuration: hardcoding the wrong region's preview host, or forgetting to set clientUrlParams.host to the correct Contentstack app URL. Both cause silent failures. * SSR state leakage: storing preview state globally in a long-lived server process. One editor's draft context leaks into another editor's request, producing non-deterministic preview results. * Wrong ssr flag: initializing with ssr: false in an SSR app causes the SDK to intercept client-side calls that never fetch data. Result: confusing flicker where server HTML shows old content, client briefly shows new content, then hydration conflicts. ## Screen: What to Show Outline item What to show on screen Opening (outline items 1-2) Contentstack entry editor: Show an entry with unpublished draft changes. Point out the "Save" vs "Publish" distinction. Click Live Preview to open the preview panel -- show how it loads the preview URL in an iframe. Whiteboard or slide: Two-plane diagram. Left side: "Published Plane" with Delivery Token arrow to  cdn.contentstack.io . Right side: "Preview Plane" with Preview Token arrow to  rest-preview.contentstack.com . Keep this visible as a reference throughout.  SDK setup (outline items 3, 5) Contentstack dashboard: Navigate to Settings > Tokens. Show where Preview Token and Delivery Token are created. Highlight that both are scoped to an environment. Contentstack dashboard: Navigate to Settings > Live Preview. Show the Preview URL field and the enable toggle. Code editor (split view): Show  .env.production  and  .env.preview  side by side. Highlight the differences:  PREVIEW\_TOKEN  present only in preview,  PREVIEW=true  only in preview. Code editor: Show the SDK initialization code. Highlight  live\_preview.enable ,  live\_preview.preview\_token ,  live\_preview.host . Then show  ContentstackLivePreview.init()  with  ssr ,  mode ,  stackSdk ,  clientUrlParams.host .  Routing (outline item 4) Browser: Open  www.example.com/blog/post  and  preview.example.com/blog/post  in side-by-side tabs. Show that the published version shows published content, the preview version shows draft content including unpublished changes. Code editor: Show the middleware or env-var logic that switches between Delivery Token and Preview Token based on mode.  SSR pattern (outline item 6) Code editor: Show the Next.js App Router server component fetching content with  draftMode() . Show the  cache: "no-store"  setting on the fetch call. Code editor: Show the client component with  ContentstackLivePreview.init({ ssr: true })  and  onEntryChange(() => router.refresh()) . Live demo: Edit a field in the Contentstack entry editor and show the SSR preview update in real time. Point out the slight delay from the server round-trip.  CSR pattern (outline item 7) Code editor: Show the React hook with  onEntryChange(fetchEntry)  and  ssr: false . Live demo: Edit a field and show the instant client-side re-render. Compare the speed to the SSR pattern.  Edit tags and transport (outline item 8) Code editor: Show  data-cslp  attributes on DOM elements. Explain the format:  content\_type.entry\_uid.locale.field\_path . Browser DevTools: Inspect an element in the preview iframe and show the  data-cslp  attribute. Hover over content in the preview panel and show the field-level highlighting.  Working implementation walkthrough (outline item 9) Full-screen code editor + preview panel: Walk through the complete flow from token creation to a working Live Preview. Show the live\_preview hash in the network tab -- the SDK sends it with each request. Failure modes (outline item 10) Browser DevTools (Console tab): Show a CORS error when  X-Frame-Options  blocks the iframe. Show how to fix it. Browser DevTools (Network tab): Show a preview request returning published content because the wrong token was used. Show the  access\_token  header vs  preview\_token  header. Browser DevTools (Network tab): Show a cached response with  Cache-Control: public  on a preview request. Show the fix:  no-store  headers. ## Veda Scenario Thread Veda is the fictional luxury jewelry brand used throughout this certification course. Use it as the running example in this video. * **Opening:** Veda's content team just hired a new marketing editor. She needs to preview a new product page for the "Matrix Link Bracelet" before publishing. Without Live Preview, she would have to publish to staging, check the page, then unpublish if something is wrong. That is a broken workflow. * **Two-plane model:** Veda runs two deployments: www.veda.com (production, Delivery Token, CDN-cached) and preview.veda.com (preview, Preview Token, no caching). Same Next.js codebase, different env vars. * **SDK initialization:** Show the Veda project's lib/contentstack.ts file. Walk through how the region is set to eu (Veda is a European brand), and how getContentstackEndpoints("eu", true) resolves the correct preview and app hosts for AWS EU. * **Draft vs published routing:** The editor opens the "Matrix Link Bracelet" product entry in Contentstack. She clicks Live Preview. Contentstack loads preview.veda.com/products/matrix-link-bracelet in the iframe. The preview deployment fetches draft content using the Preview Token. * **SSR pattern:** Veda's product pages are server-rendered for SEO (title, description, structured data). The server fetches draft content on each preview request. router.refresh() handles updates. * **CSR pattern:** Veda's "Related Products" carousel is client-rendered. It uses onEntryChange to re-render in place when the editor changes related product references. * **Edit tags:** The editor hovers over the product title on the preview page. The data-cslp="product.blt\_matrix\_link\_001.en-us.title" attribute lights up, showing her exactly which field maps to that heading. She clicks and edits in place. * **Failure mode demo:** Show what happens if Veda's preview deployment accidentally uses the Delivery Token -- the new "Matrix Link Bracelet" entry (never published) returns a 404 in preview. Fix it by swapping to the Preview Token. ## Transitions 1. **Item 1 to 2:** "So if preview is not free, how does Contentstack actually separate draft content from published content? It comes down to two delivery planes." 2. **Item 2 to 3:** "Knowing the model is one thing -- now let us look at what your frontend code needs to support it." 3. **Item 3 to 4:** "The SDK is initialized, but how does your app decide when to use the Preview Token versus the Delivery Token? That is routing." 4. **Item 4 to 5:** "Let me show you exactly where this is configured -- both in Contentstack's dashboard and in the frontend code." 5. **Item 5 to 6:** "Configuration is done. Now let us see how preview actually works at runtime, starting with server-side rendering." 6. **Item 6 to 7:** "SSR preview works, but it has a round-trip delay. Client-side rendering gives you instant updates -- here is how." 7. **Item 7 to 8:** "Both patterns rely on the same underlying mechanisms: onEntryChange, edit tags, and postMessage transport. Let us look at those." 8. **Item 8 to 9:** "Now that you understand all the pieces, let us put them together in a complete working implementation." 9. **Item 9 to 10:** "Before we wrap, let me show you the most common ways Live Preview breaks -- so you can avoid them." 10. **Closing to Video 9:** "Live Preview gives editors visibility into draft content. But seeing content is only half the story -- in the next video, we will look at Visual Builder, which lets editors actually edit content in place, directly on the page." ## Common Mistakes to Call Out * **Using the Delivery Token in the preview deployment.** Editors only see already-published content. New entries and draft changes are invisible. The bug hides during setup because developers test with already-published entries. It surfaces when an editor creates a new entry and gets a 404. * **Applying production cache rules to the preview host.** CDN, browser, and framework fetch caches all need explicit no-cache configuration for preview. One missed layer means editors see stale content and lose trust in the entire preview system. * **Mismatched URL paths between preview and production.** If preview uses a different routing scheme (e.g., /preview/blog/slug instead of /blog/slug), Contentstack cannot construct the correct preview URL. Editors land on 404 pages. * **Setting** **ssr: false** **in an SSR application.** The SDK tries to intercept client-side SDK calls that never actually fetch data. Result: server HTML shows old content, client briefly flashes new content, then hydration conflicts cause unpredictable behavior. * **Forgetting to disable fetch caching in SSR preview mode.** In Next.js App Router, fetch() is cached by default. Without cache: "no-store" on preview requests, the server returns stale published content even with a Preview Token. * **Using** **window.location.reload()** **instead of** **router.refresh()** **in Next.js.** Full page reload discards client state, resets scroll position, and forces a complete HTML re-parse. router.refresh() re-runs server components smoothly. * **Storing preview state globally in a long-lived server process.** One editor's draft context leaks into another editor's request, producing non-deterministic preview. Preview state must be request-scoped. * **Missing** **clientUrlParams.host** **configuration.** The SDK needs the Contentstack app URL for your region to establish the postMessage bridge. Without it, Live Preview silently fails to communicate with the entry editor. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 8 — Live Preview Architecture and Preview Routing** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 24 — Video Production Plan : Video 9 — Visual Builder, Releases, and Future-State Preview #### Lesson text # Video 9 — Visual Builder, Releases, and Future-State Preview Attribute Details Course 4 (Preview, Visual Builder, and Releases), Module 4.1 (lessons 4-5) + Module 4.2 Covers Lessons 4.1.4, 4.1.5, 4.2.1, 4.2.2, 4.2.3 Priority Critical Length 20-30 min Format Screencast (code editor + Visual Builder in action) Status Not started ## Why This Video Matters This combines one of the most visual platform features with one of the most operationally important publishing topics. Visual Builder is the showstopper demo of the entire certification. ## Outline 1. What Visual Builder adds on top of Live Preview: click-to-edit, drag-and-drop, in-context component management 2. Architecture: how Visual Builder communicates between the Contentstack UI and your frontend 3. data-cslp and editable tagging 4. Implementation walkthrough: adding Visual Builder SDK, annotating components, registering editable regions 5. Show the editor experience: clicking on a component, editing inline, seeing changes live 6. Visual Builder with GraphQL: how to set up when your frontend uses GraphQL instead of REST 7. Localization in Visual Builder: switching locales, seeing locale-specific content render 8. Releases: bundle multiple entries and assets into a single coordinated publish action 9. Veda use case: new collection launch — product entries, landing page, navigation, assets all go live together 10. Scheduling: set a release to publish at a future date/time 11. Version comparison, rollback, and previewing future states ## Key Lines "Visual Builder only works well when the frontend is intentionally prepared for it." "Visual Builder turns your frontend into an editor's canvas. That is the promise of headless done right." "Previewing what will happen later is often more valuable than previewing what exists now." ## Detailed Talking Points ### 1\. What Visual Builder adds on top of Live Preview * Live Preview shows your frontend with draft content. Visual Builder goes further: it turns that frontend into an editable surface. * Click-to-edit: editors click directly on rendered content (a headline, an image, a CTA) and edit in place. No switching between the entry form and a preview panel. * Drag-and-drop: reorder modular block components visually, and Visual Builder reflects the new order instantly. * In-context component management: add, remove, or reconfigure components without leaving the rendered page view. * Visual Builder renders your actual production frontend inside the Contentstack UI via an iframe. Editors see exactly what visitors will see. * Key dependency: if Live Preview is not working, Visual Builder will not work either. It extends Live Preview, it does not replace it. ### 2\. Architecture: how Visual Builder communicates between the Contentstack UI and your frontend * Contentstack loads your frontend in an iframe inside the entry editor. * Visual Builder scans the iframe DOM for data-cslp attributes and creates clickable overlay regions around each tagged element. * When the editor clicks a tagged region, Visual Builder reads the data-cslp value to identify the field and opens an inline editing panel. * Communication happens over the postMessage API between the parent Contentstack window and your iframe. * The Live Preview SDK receives updated data via postMessage and re-renders the element, giving immediate visual feedback. * Changes are saved to the entry's draft state in Contentstack automatically. * MutationObserver watches for DOM changes to keep overlays positioned correctly. ### 3\. data-cslp and editable tagging * The data-cslp attribute is the contract between your frontend and Visual Builder. Without it, nothing is editable. * Format: content\_type\_uid.entry\_uid.locale.field\_path -- four parts, dot-separated. * Each part serves a purpose: content type identifies the schema, entry UID identifies the specific entry, locale identifies the language, and field path maps to the exact field. * For nested fields (groups), use dot notation: seo.meta\_title, not seo\_meta\_title. * For modular blocks, include the array index and block type: components.0.hero.title, not components.0.title. * For reference fields, decide whether to tag the reference field itself (lets editor change which entry is referenced) or the referenced entry's fields (lets editor edit the referenced content). * Incorrect paths cause silent failures: the element renders but no overlay appears, no error in the UI. * Use addEditableTags() from @contentstack/delivery-sdk to auto-generate tag values instead of hand-coding them. It attaches $ properties to each field. ### 4\. Implementation walkthrough * Step 1: Verify Live Preview works first. Check your preview deployment fetches draft content, the SDK is initialized with correct region-specific hosts, and onEntryChange callbacks fire. * Step 2: Add data-cslp attributes to all rendered content. Use addEditableTags() where possible. Pay special attention to modular blocks (include array index), group fields (dot notation), reference fields (choose the right target), and image/file fields. * Step 3: Configure Visual Builder in Contentstack stack settings under Settings > Live Preview. Enable Visual Builder, set the preview URL, and configure content type URL mapping. * Step 4: Conditionally load the Live Preview SDK. Use @contentstack/live-preview-utils, set mode: "builder", configure clientUrlParams.host to the correct application host, and set editButton.exclude: \["outsideLivePreviewPortal"\]. * Step 5: Test in the Contentstack entry editor. Switch to Visual Builder view and verify hoverable highlights, click-to-edit, and real-time updates. ### 5\. Show the editor experience * Open an entry in Contentstack and switch to Visual Builder view. * Hover over elements: highlight regions appear around every tagged element. * Click on a text field: an inline text input appears. Type changes and watch them render immediately. * Click on an image field: a file picker opens. Select a new image and it swaps in the rendered page. * Click on a rich text field: the JSON RTE editor opens inline. * Demonstrate editing a modular block component, then reordering blocks via the entry form and watching Visual Builder reflect the change. * Show that the edit button only appears inside the Contentstack portal, not when accessing the preview URL directly. ### 6\. Visual Builder with GraphQL * GraphQL uses a different preview endpoint (graphql-preview.contentstack.com pattern) and requires the Preview Token instead of Delivery Token. * The live\_preview hash must be passed as a header on each GraphQL request during a live editing session. Without it, there is a delay between keystrokes and preview updates. * data-cslp values always reference the content type schema field UID, not GraphQL aliases. If your query aliases heroTitle: title, the data-cslp must still use title. * When using GraphQL without the Contentstack JS SDK, you do not pass stackSdk to ContentstackLivePreview.init(). Instead, you manage data flow manually through onEntryChange callbacks. * For SSR with GraphQL, trigger router.refresh() in the onEntryChange callback so the server re-runs the query with the updated hash. ### 7\. Localization in Visual Builder * When an editor switches locale in the Contentstack entry editor, a postMessage is sent to the preview iframe with the new locale. * The Live Preview SDK detects the locale change and can trigger navigation to the locale-specific URL or a content refresh. * The locale in data-cslp must be dynamic and match the content being rendered. Hardcoding en-us breaks Visual Builder for every other locale. * Use ContentstackLivePreview.getLocale() in your onEntryChange handler to get the current locale and navigate accordingly. * Locale fallback behavior: if an entry is not localized for ja-jp, the preview shows English fallback content. This is correct behavior but can confuse editors. Consider adding a visual fallback indicator. ### 8\. Releases: coordinated publishing * A Release is a named collection of entries and assets that publish or unpublish together atomically. * Each item carries a publish or unpublish action, so a single Release can swap old content for new content in one operation. * Without Releases, coordinating multi-entry campaigns means publishing items one by one and hoping the timing holds. A hero banner goes live before the landing page it links to. A nav item points to a page that does not exist yet. * Three ways to add items: from the entry editor (Add to Release), from bulk actions in the entry list, or from the Release detail screen. * Releases target specific environments and locales. Most teams still promote progressively: staging first, then production. ### 9\. Veda use case: new collection launch * Veda is launching the Holiday Collection. The campaign touches 12 entries across 4 content types: homepage hero, 8 Digital Dawn products, a product line update, a navigation header change, and an old campaign page to unpublish. * Without Releases, an editor manually publishes each entry and remembers to unpublish the old banner. The margin for error is significant. * With a Release named "Holiday Collection 2025": editors prepare entries over weeks, adding each to the Release as it reaches approval. The Release manager reviews the complete list. Schedule for November 28 at midnight. All 12 entries deploy atomically. * The customer experience is seamless: one moment the site shows the previous campaign, the next it shows the Holiday Collection. No intermediate state. * Call out the Release API: Releases can be created and managed programmatically, enabling CI/CD integration and automated campaign management. ### 10\. Scheduling: set a release to publish at a future date/time * Open the Release, click Schedule Release, select environment, set date and time, choose locale, confirm. * Once scheduled, the Release enters a locked state. You cannot add or remove items without first unscheduling. * This lock prevents last-minute unreviewed changes from slipping into a coordinated deployment. * Scheduling is timezone-aware. Set the deployment time according to your business needs, not your team's timezone. * Entries must be in a publishable workflow stage before the Release fires. If an entry is stuck in "Review," it may be silently skipped or block the entire deployment. ### 11\. Version comparison, rollback, and previewing future states * Every save creates a new, immutable, complete snapshot of the entry. Not a diff, not a delta. Any version can be loaded independently. * Version comparison: select two versions and see a field-by-field diff. Additions, deletions, modifications highlighted. * Restoring a previous version creates a new version (never overwrites history). Entry at version 10, restore version 7, entry becomes version 11 with version 7's content. Versions 8-10 remain accessible. * Restoring does not republish. The restored content updates the draft. You must explicitly publish to push changes live. * Previewing future states: standard Live Preview shows a single entry's draft. Time travel preview composites all scheduled changes to show the full site state at a target date. * Three approaches to future-state preview: preview all drafts (simplest), date-parameterized preview (more targeted), or Release-scoped preview (most precise but most code). * Overlapping Releases targeting the same entry on the same date have no automatic conflict resolution. The last one to execute wins. ## Screen: What to Show Outline item What to show on screen Opening (outline items 1-2) Start with the Contentstack entry editor showing a page entry. Toggle from the standard form view to Visual Builder view. Let the iframe load and show your actual frontend appearing inside the CMS. Briefly show the browser DevTools Elements panel with  data-cslp  attributes visible on DOM elements, demonstrating the field-to-DOM mapping. data-cslp tagging (outline item 3) Switch to VS Code. Show a component file with  data-cslp  attributes on elements. Highlight the format:  content\_type\_uid.entry\_uid.locale.field\_path . Show  addEditableTags()  usage: the call to  contentstack.Utils.addEditableTags(entry, "page", true)  and the resulting  entry.$?.title  spread syntax in JSX. Show a modular block component with the index in the field path:  components.${index}.hero.title . Implementation walkthrough (outline item 4) Show the Live Preview SDK initialization code with  mode: "builder" . Point out  clientUrlParams.host ,  editButton.exclude , and the conditional loading pattern. Show the  next.config.js  CSP headers allowing  frame-ancestors 'self' https://app.contentstack.com . Editor experience demo (outline item 5) Back in Visual Builder in the browser. Hover over elements to show highlight overlays appearing. Click on a title and edit it inline. Show the change rendering live. Click on an image field and show the file picker. Select a new image and watch it swap. Edit a rich text block inline. This should be the most visually impressive part of the video. Let it breathe. GraphQL setup (outline item 6) Show the GraphQL preview client code in VS Code. Point out the preview endpoint, the  live\_preview  hash header, and the  onEntryChange  callback with  router.refresh() . Show a  data-cslp  attribute next to a GraphQL query with an alias, and explain that the attribute must use the schema field UID, not the alias. Localization (outline item 7) In Visual Builder, switch the locale dropdown in the Contentstack entry editor. Show the preview iframe updating to render locale-specific content. Show the dynamic locale in a  data-cslp  attribute in code:  page.${entry.uid}.${locale}.title . Releases (outline items 8-9) Navigate to Publish Queue > Releases in the Contentstack UI. Create a new Release, name it descriptively. Add entries to the Release from the entry editor and from the Release detail screen. Show both publish and unpublish actions on items. Show the Veda Holiday Collection Release with its item list: product entries, landing page, navigation update, old campaign page marked for unpublish. Scheduling (outline item 10) Click Schedule Release. Set the environment, date/time, and locale. Show the locked state after scheduling. Show the Publish Queue with pending scheduled items. Versioning and future-state preview (outline item 11) Open an entry's version history. Show the version list with numbers, authors, timestamps. Select two versions and show the diff view with field-level changes highlighted. Demonstrate restoring a version: click Restore, show the new version created, point out the version number incremented. Show the publish queue with scheduled Releases and explain the "time travel" concept. If you have a Release-aware preview endpoint, show the composite future state. ## Veda Scenario Thread Veda is launching the Holiday Collection -- a coordinated campaign touching multiple content types. This thread runs through the entire video: 1. **Visual Builder setup:** Show Veda's kickstart-veda marketing homepage in Visual Builder. The page uses modular blocks (hero, list, rich\_text, two\_column). Demonstrate editing the hero title, a product card from a reference field, and rich text content directly in the rendered page. 2. **Tagging complexity:** Veda's list block stores content in a reference field. The page-level edit tag for the reference picker is page...components.{index}.list.reference, while nested product fields use the referenced entry's own content type and UID (product.{uid}.en-us.title). Walk through this distinction live. 3. **Localization:** Veda operates in multiple locales. Show switching from en-us to another locale in Visual Builder and seeing the localized hero text update. Point out the dynamic locale in data-cslp attributes. 4. **Release assembly:** Veda's Holiday Collection Release includes: homepage with Holiday hero (publish), 8 Digital Dawn products (publish), Digital Dawn product line update (publish), header with "Holiday" menu item (publish), and old campaign page (unpublish). Walk through adding items and reviewing the complete list. 5. **Scheduling the launch:** Schedule the Holiday Collection Release for November 28 at midnight. Show the locked state and the publish queue entry. 6. **Version control during prep:** While preparing the campaign, an editor introduces a typo in a product entry. Show the version history, compare the current version to the previous one, restore the correct version, and verify the fix before re-adding to the Release. 7. **Future-state preview:** Preview what the homepage will look like on November 28 after the Release deploys. All campaign content appears together. The old campaign page is gone. Everything is validated before the scheduled date. ## Transitions 1 to 2: "Now that you know what Visual Builder gives editors, let's look at the architecture that makes it possible." 2 to 3: "The key to that architecture is one HTML attribute: data-cslp." 3 to 4: "Knowing the format is one thing -- let's walk through the full implementation, step by step." 4 to 5: "With everything wired up, here is what the editor actually experiences." 5 to 6: "That was the REST setup. If your frontend uses GraphQL, the setup differs in a few important ways." 6 to 7: "GraphQL covered. Now let's handle localization, because hardcoding en-us will break Visual Builder for every other locale." 7 to 8: "Visual Builder handles the editing experience. But when you need multiple entries to go live together, you need Releases." 8 to 9: "Let's make this concrete with Veda's Holiday Collection launch." 9 to 10: "The Release is assembled. Now we schedule it so everything deploys automatically at the right time." 10 to 11: "Before we wrap up, there is one more operational layer: version control and previewing what the site will look like after a scheduled Release deploys." 11 to closing: "That covers Visual Builder, Releases, and future-state preview. In the next video, we move into workflows, branches, and team collaboration -- the governance layer that keeps all of this organized at scale." ## Common Mistakes to Call Out 1. **Missing** **data-cslp** **on modular block children:** Tagging only the modular block container produces a single large clickable region that opens the full block editor instead of field-level editing. Tag each field individually, including the array index in the field path. 2. **Incorrect field paths for nested content:** Using components.0.title instead of components.0.hero.title for a modular block, or seo\_title instead of seo.meta\_title for a group field. Visual Builder fails silently -- no overlay, no error. Always verify paths against the content type schema. 3. **Deploying Visual Builder SDK to production without conditional loading:** The SDK only activates in the iframe context, but including it in the production bundle adds unnecessary JavaScript weight. Conditionally import based on your preview mode flag. 4. **Using GraphQL aliases in** **data-cslp** **values:** If your query uses heroTitle: title, the data-cslp must still reference title, not heroTitle. Visual Builder resolves against the schema, not your query structure. 5. **Hardcoding locale in** **data-cslp** **for multi-locale sites:** Setting en-us when rendering French content causes Visual Builder to open the English field editor. Always derive the locale dynamically from routing context. 6. **Omitting** **frame-ancestors** **CSP directive on the preview host:** Without it, the browser blocks the iframe entirely. Visual Builder shows a blank panel. This is easily missed because the preview site works when accessed directly in a browser tab. 7. **Adding entries to a Release that have not completed workflow review:** If an entry is stuck in a non-publishable workflow stage when the Release fires, it may be silently skipped or block the entire deployment. Verify workflow stages before scheduling. 8. **Forgetting to include referenced assets in a Release:** Entries go live but render with broken images because the assets were not in the Release and were not already published to the target environment. 9. **Assuming restore republishes content:** Restoring a previous version updates the draft only. The live site continues serving the old content until you explicitly publish. Editors often miss this step. 10. **Previewing individual entries and assuming the full page is correct:** A single entry from a Release renders fine, but a navigation change in the same Release conflicts with the layout. Always validate the composite page state using a Release-aware or all-drafts preview. 11. **Not accounting for overlapping scheduled Releases:** Two Releases modify the same entry on the same date. No automatic conflict resolution exists. The last one to execute wins. Review the publish queue for collisions. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 9 — Visual Builder, Releases, and Future-State Preview** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 25 — Video Production Plan : Video 10 — Workflow, Automation Hub, and Branch Strategy #### Lesson text # Video 10 — Workflow, Automation Hub, and Branch Strategy Attribute Details Course 5 (Workflow, Branches, and Collaboration) Covers Lessons 5.1.1, 5.1.2, 5.1.3, 5.2.1, 5.2.2, 5.2.3, 5.2.4 Priority Core Length 18-24 min Format Screencast (Contentstack UI + diagrams) Status Not started ## Why This Video Matters This is ideal as a single operational overview video because the course is conceptually linked from start to finish. Strong operations make strong models and APIs sustainable. ## Outline 1. Content lifecycle from draft to publish: stages, transitions, permissions 2. Why workflows matter: prevent accidental publishing, enforce review gates, create accountability 3. Walk through creating a Veda workflow: Writer drafts, Editor reviews, Manager approves, auto-publish on approval 4. Workflow rules: who can transition between stages, notification triggers 5. Automation Hub: trigger actions based on workflow transitions (Slack notification, webhook, external system update) 6. Show a practical automation: entry reaches "Approved" stage, notify the frontend team 7. When content branches are the right tool: redesigning a content type without disrupting the live site 8. Compare and merge: reviewing differences between branches, resolving conflicts 9. Parallel development: multiple teams working on different content model changes simultaneously 10. Branch hygiene: naming conventions, lifecycle policies, when to merge and delete ## Key Lines "Workflows turn 'be careful' into 'the system prevents mistakes'." "Branches are not environments, and environments are not branches." "Good workflow design reduces coordination cost without becoming bureaucracy." ## Detailed Talking Points ### 1\. Content lifecycle from draft to publish: stages, transitions, permissions * Every entry lives in exactly one workflow stage at a time: Draft, Review, Approved, Published. * Transitions are explicit actions, not implicit — someone (or an automation) moves the entry forward or backward. * The "Published" stage is set automatically by the system when the publish action completes; you never drag an entry into it manually. * Publishing and workflow status are independent dimensions. An entry can be "Approved" and published to zero environments. Always check both when debugging visibility. * Publish rules tie workflow stages to environments — Draft publishes nowhere, Review publishes to dev/staging, Approved publishes to production. * Unpublishing removes an entry from a delivery environment without deleting it from the CMS. Useful for seasonal content, corrections, and environment-specific visibility. * Bulk workflow operations exist: bulk stage transitions, bulk publish, bulk unpublish — all respecting the same permission rules as individual operations. ### 2\. Why workflows matter: prevent accidental publishing, enforce review gates, create accountability * Without workflows, any user with publish permissions can push any entry to production regardless of readiness. * Workflows turn informal "be careful" policies into enforced system behavior. * Every transition is logged in the audit trail — who moved what, when, and to which stage. * Workflow stages give teams filterable queues: see all entries stuck in Review, identify bottlenecks at a glance. * The goal is reducing coordination cost without creating bureaucracy. Match stage count to team size and content risk. * Without publish rules configured alongside workflows, stages are advisory only — they label but do not prevent. ### 3\. Walk through creating a Veda workflow: Writer drafts, Editor reviews, Manager approves, auto-publish on approval * Navigate to Settings > Workflows, click "Add Workflow." * Define stages in sequence: Draft (gray), Editorial Review (blue), Manager Approval (green). * For each stage, set a name, color, and description explaining what should happen there. * Assign transition permissions: Writers can move Draft to Editorial Review. Editors can move Editorial Review to Manager Approval or reject back to Draft. Managers can approve. * Assign the workflow to the Veda "Product Line" content type. * Configure publish rules: Draft publishes to nothing, Editorial Review publishes to development and staging, Manager Approval publishes to all environments including production. * Show that different content types can have different workflows — a blog post might have a simpler two-stage flow. * Mention superuser bypass: Owners can skip stages for emergencies, but every bypass is logged in the audit trail. ### 4\. Workflow rules: who can transition between stages, notification triggers * Permissions are configured through Settings > Roles, not through the workflow itself. * Each role gets specific workflow permissions: Content Author creates and submits, Editor reviews and forwards or rejects, Manager gives final approval. * These permissions create a chain of responsibility — no role can interfere with another role's part of the lifecycle. * Notification triggers fire when entries move between stages. Reviewers get notified when entries land in their queue. * Workflow assignment can vary by content type — a product monograph might need Legal Review and Compliance stages that a blog post does not. * A common design mistake is building stages that match the org chart rather than the content process. Design around distinct review activities, not job titles. ### 5\. Automation Hub: trigger actions based on workflow transitions * Automation Hub is Contentstack's built-in automation engine — visual flow builder in the Automate section. * It connects CMS events (publish, stage change, asset upload) to actions (Slack messages, Jira tickets, auto-publish) without custom code. * Triggers include: entry created, entry updated, entry published, workflow stage changed, asset uploaded, release deployed. * Triggers should be scoped narrowly to specific content types or environments — a trigger on "any entry published" across all content types generates enormous noise. * Actions can be internal (move to workflow stage, update entry field, publish entry, create task) or external via connectors (Slack, Teams, Jira, Asana, webhook). * Connectors handle authentication, retry logic, and payload formatting — you configure once and reuse across automations. * Conditional logic supports if/then branching based on field values, locale, environment, or user. * Automations execute asynchronously and independently — no guaranteed execution order between multiple automations on the same trigger. ### 6\. Show a practical automation: entry reaches "Approved" stage, notify the frontend team * Create a new automation in the Automate section: "Notify Frontend on Product Approval." * Trigger: Workflow stage changed, scoped to the "Product Line" content type, specifically the "Approved" stage. * Action: Send Slack message to #frontend-deploys with template variables: entry title, content type, user who approved. * Walk through the template variable syntax: double curly braces like {{entry.title}} and {{user.name}}. * Show a second pattern: auto-publish to staging on approval. Trigger on "Approved" stage, action is "Publish entry to staging environment." * Mention the limitation: there is no undo for automation actions. A misconfigured flow that publishes to production prematurely must be reversed manually. * Show where to test the automation before activating it on production content. * Call out that connector auth tokens can expire — monitor connector health proactively. ### 7\. When content branches are the right tool * Branches fork content type schemas, not code. They create parallel versions of your content model. * The problem they solve: how do you restructure a content type without breaking the production site that depends on the current schema? * Without branches, you either break production immediately or coordinate a high-risk synchronized cutover. * Branches include content type definitions, global field definitions, and optionally entries. They do NOT include environments, webhooks, workflows, roles, or Automation Hub configs — those are stack-level. * The main branch is the default for all API queries. Creating a branch changes nothing about production until you merge. * Use branches for: breaking schema changes, new content types needing iteration, large migrations, coordinating frontend and CMS changes. * Do NOT use branches for: content-only changes (use workflow stages), environment isolation (use environments), small non-breaking field additions, or urgent hotfixes. * Critical distinction: branches are NOT environments. Branches control how content is structured. Environments control where content is delivered. ### 8\. Compare and merge: reviewing differences between branches, resolving conflicts * Always use the compare view before merging — it shows field-level additions, removals, and modifications per content type. * Three categories of diff: added content types, modified content types, deleted content types. * Field-level diff shows: fields added, fields removed, fields modified (type changes, validation changes, renames). * Field removal in a merge means permanent data loss on existing entries. There is no undo. * Merge strategies: merge\_prefer\_base (default, keeps target values on conflict), merge\_prefer\_compare (keeps source values), overwrite\_with\_compare, merge\_new\_only. * Merges cannot be automatically reversed. Create a backup branch from the target before merging. * Pre-merge checklist: review all changes, check for field removals, verify existing entries will not break, coordinate with frontend team, communicate with content team, choose timing. * Post-merge: verify content types, test delivery API, deploy frontend, re-publish affected entries, populate new required fields. ### 9\. Parallel development: multiple teams working on different content model changes simultaneously * Multiple branches can exist simultaneously, each serving a different team's schema changes. * Use branch naming conventions: feature/, migration/, redesign/, fix/, experiment/ — signals purpose and expected lifespan. * Point QA builds at specific branches via the branch SDK parameter. Each team tests in isolation. * Merge sequencing matters: merge the smallest and most isolated branch first, then branches modifying fewer content types, then the broadest branch last. * Re-compare against main between each merge — earlier merges change what the next merge encounters. * There is no built-in rebase. If a branch diverges significantly, you create a fresh branch from current main and manually re-apply changes. * Communication is essential: maintain a branch registry, announce merges before and after, inform editors about incoming content type changes. ### 10\. Branch hygiene: naming conventions, lifecycle policies, when to merge and delete * Every branch should follow a defined lifecycle: create, develop, test, merge, delete. * Set time limits: 0-14 days is normal, 14-30 days needs a status update, 30-60 days needs a review, 60-90 days is at-risk, 90+ days is presumed stale. * Assign a single person (tech lead or CMS architect) to own branch governance. Shared responsibility means no responsibility. * Delete branches immediately after a successful merge and post-merge verification. Do not keep them "just in case." * Treat stale branches as technical debt — they accrue interest the longer they sit. * Monitor branch drift periodically for long-lived branches: compare to main to assess divergence. * Abandoned branches create confusion for new team members, waste resources, and increase merge complexity for active branches. * Weekly branch review in standup: two minutes reviewing the branch registry catches sprawl before it develops. ## Screen: What to Show Outline item What to show on screen 1\. Content lifecycle Contentstack entry list view filtered by workflow stage. Show the colored stage labels. Open a single entry and point out the workflow stage indicator. Show the mermaid diagram: Draft > Review > Approved > Published with rejection loops. 2\. Why workflows matter Entry list with 30 entries in Review and 2 in Approved — visual bottleneck. Show the audit log for a workflow transition: who, what, when. Show what happens when you try to publish a Draft entry to production without publish rules (it succeeds — that is the problem). 3\. Veda workflow creation Live screencast in Settings > Workflows. Create a new workflow step by step. Add three stages with colors. Configure transition permissions per role. Assign the workflow to the Product Line content type. Then go to Settings > Workflows > Publish Rules and create rules tying stages to environments. 4\. Workflow rules Settings > Roles screen. Show how a Content Author role is configured with specific workflow permissions. Show the permission matrix: which roles can transition to which stages. Brief shot of a notification email or in-app notification triggered by a stage transition. 5\. Automation Hub Navigate to the Automate section. Show the list of existing automations. Open the flow builder. Show the trigger selector with the list of available CMS events. Show the connector library: Slack, Jira, Teams, webhook. Show the conditional logic branching UI. 6\. Practical automation Build the automation live: select trigger (workflow stage changed to Approved for Product Line), add Slack action, configure channel and message template with curly-brace variables. Hit the test button to simulate. Show the Slack message arriving in the channel. Then show a second automation: auto-publish to staging on approval. 7\. Branches Settings > Branches screen. Create a new branch from main. Show the branch creation form (name, source). After creation, switch to the branch and show the content type list — identical to main at creation time. Modify a content type on the branch (add a field). Switch back to main and show the content type is unchanged. Show the SDK config with the branch parameter. 8\. Compare and merge Open the compare view for the branch vs main. Walk through the diff: added fields in green, removed fields in red, modified fields highlighted. Show the merge strategy selector. Show the confirmation dialog. After merge, open the content type on main and verify the new field is present. 9\. Parallel development Show two or three branches in the branch list, named with conventions (feature/, migration/). Show a CI/CD config snippet with the branch environment variable. Show a QA site rendering content from a branch. Show the branch registry spreadsheet or doc. 10\. Branch hygiene Show a cluttered branch list with old branches. Run the branch audit script (or show its output) — branches flagged by age. Delete a stale branch. Show the clean branch list afterward. Show the time-limit policy table as a slide or overlay. ## Veda Scenario Thread Veda is a direct-to-consumer brand managing product launches across multiple regions. Throughout this video, Veda's operational needs drive every concept: * **Workflow creation (items 1-4):** Veda's content team has writers, regional editors, and a marketing manager. Writers draft product descriptions. Regional editors review for market accuracy and tone. The marketing manager gives final approval before production publish. Build this exact workflow live in the Contentstack UI, using Veda's "Product Line" content type. * **Automation Hub (items 5-6):** When a Veda product page reaches the "Approved" stage, the frontend team needs to know so they can prepare the deployment. Build a Slack notification automation for this. Also show auto-publishing approved content to the staging environment so the marketing manager can preview before the manual production publish. * **Branches (item 7):** Veda's development team needs to add a "specifications" modular block and a "sustainability\_statement" rich text field to the Product Line content type. These are breaking changes — the live site expects the current schema. Create a branch called feature/product-specs-v2, make the changes there, and show that the production site is unaffected. * **Compare and merge (item 8):** After Veda's dev team finishes iterating on the branch, show the compare view between feature/product-specs-v2 and main. Walk through the diff, noting the new fields and confirming no fields were accidentally removed. Execute the merge and verify on main. * **Parallel development (item 9):** Mention that Veda's design team is simultaneously working on a redesign/homepage-hero branch to restructure the homepage into modular blocks. Two branches, two teams, zero interference — because the branches modify different content types. * **Branch hygiene (item 10):** After the merge, delete feature/product-specs-v2 immediately. Show the branch registry entry being marked as merged and the branch being removed from the list. Reference Veda's policy: branches older than 30 days get reviewed, branches older than 60 days get escalated. ## Transitions 1 to 2: "That is the lifecycle — now let us talk about why encoding it into the system matters more than telling your team to be careful." 2 to 3: "So let us build this in Contentstack — here is what a real workflow looks like for Veda's product content." 3 to 4: "The stages are set up, but who gets to push content through each gate — that is where role-based permissions come in." 4 to 5: "Manual transitions work, but what if the system could react automatically when content moves between stages?" 5 to 6: "Let me show you a concrete example — we will wire up a Slack notification that fires the moment a Veda product gets approved." 6 to 7: "Workflows handle the content lifecycle. But what about the content model itself — what happens when you need to change the structure without breaking production?" 7 to 8: "You have made your changes on a branch. Now you need to get them back to main — and that is where compare and merge earns its keep." 8 to 9: "One branch is straightforward. But what happens when three teams each have their own branch running at the same time?" 9 to 10: "Parallel branches work great until they do not — let us talk about the discipline that keeps branches from becoming a liability." 10 to Video 11: "Workflows, automations, and branches give you operational control over your content model. In the next video, we shift to the developer experience — webhooks, extensions, and building custom integrations on the Contentstack platform." ## Common Mistakes to Call Out 1. **Confusing workflow stage with publish state.** An entry in "Approved" is not published. An entry that is published is not necessarily in the "Published" workflow stage. These are two separate systems — workflow tracks editorial readiness, publishing controls delivery availability. Always check both dimensions. 2. **Skipping review for "small changes."** Typo fixes are how broken links, deleted paragraphs, and accidental field clears reach production. The workflow exists to catch mistakes, and mistakes do not scale with perceived change size. 3. **Creating workflow stages without configuring publish rules.** Without publish rules, stages are advisory only — a Draft entry can still be published to production. Workflows and publish rules must be configured together. 4. **Creating stages without assigning role-based permissions.** A workflow stage without permissions is just a label. If anyone can move an entry to "Approved," the stage provides no governance. 5. **Building workflows that match the org chart instead of the content process.** If "VP Review" and "Director Review" check the same things, merge them into one stage. Design around distinct review activities, not job titles. 6. **Not scoping Automation Hub triggers to specific content types.** A trigger on "any entry published" fires for every content type in the stack. If you only care about blog posts, the automation runs unnecessarily for every other publish event. 7. **Building automations that depend on execution order.** Multiple automations on the same trigger have no guaranteed execution order. If one sets a field value and another reads it, the reader may execute first. Put sequential operations in a single automation flow. 8. **Treating Contentstack branches like git branches.** Git branches create parallel code files and merge line-by-line. Contentstack branches fork content type schemas and merge at the field level. The mental model, merge mechanics, and conflict resolution are all different. 9. **Creating branches for content editing instead of schema changes.** If editors want to draft entries without affecting the live site, they need workflow stages and publish rules, not branches. Branches are for content model changes only. 10. **Forgetting that stack-level settings are not branched.** Environments, webhooks, workflows, roles, and Automation Hub configs are shared across all branches. Modifying a webhook affects events on every branch. 11. **Merging without reviewing the compare diff.** Every merge can remove fields, delete content types, and destroy data. Merging without reviewing the diff is deploying without reading the pull request. 12. **Forgetting that field removal means permanent data loss.** When a merge removes a field from a content type, all data in that field on existing entries is gone. There is no undo. 13. **Not coordinating merges with frontend deployments.** A merge that changes the API response shape without a frontend update breaks the site. Plan merges and frontend deployments as a coordinated operation. 14. **Keeping merged branches "just in case."** After a merge, the branch contains no unique information. If you need a backup, create a backup branch from main before merging, not after. Delete the source branch once the merge is verified. 15. **No single person responsible for branch governance.** When branch management is everyone's responsibility, it is no one's responsibility. Designate one person to own branch hygiene. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 10 — Workflow, Automation Hub, and Branch Strategy** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 26 — Video Production Plan : Video 11 — When To Customize: Configuration vs Apps vs Webhooks #### Lesson text # Video 11 — When To Customize: Configuration vs Apps vs Webhooks Attribute Details Course 6 (Extending and Customizing Contentstack), Module 6.1 Covers Lessons 6.1.1, 6.1.2, 6.1.3, 6.1.4 Priority Critical Length 18-25 min Format Screencast (Developer Hub + code editor) Status Not started ## Why This Video Matters This is a high-value decision video. Every customization creates long-term ownership cost. The right question is not whether you can build it, but whether you should own it. ## Outline 1. Configuration vs customization: always try configuration first; customize only when configuration cannot solve the problem 2. The decision framework: when to use native features, marketplace apps, custom apps, or webhooks 3. Marketplace apps: browse, install, and configure pre-built integrations — show a few useful examples 4. Building custom apps: Developer Hub, App SDK, UI locations (custom fields, sidebar widgets, dashboard widgets, full-page apps) 5. Walk through building a simple custom field or sidebar widget 6. App hosting options: self-hosted vs Contentstack-hosted 7. Webhooks: event-driven integration — trigger external systems when content changes 8. Show creating a webhook, configuring trigger conditions, and handling the payload 9. Webhook security: verifying signatures, handling retries, idempotency 10. Examples of over-customization and how to avoid it ## Key Lines "Every customization creates long-term ownership cost." "The right question is not whether you can build it, but whether you should own it." "Built-in features usually age better than custom code." ## Detailed Talking Points ### 1\. Configuration vs customization: always try configuration first * Contentstack ships with field validation rules, workflow stages, publish rules, roles and permissions, taxonomies, and Automation Hub connectors. Most teams underestimate how much this covers. * Field validation alone handles required fields, unique constraints, regex patterns, character limits, number ranges, and select-field options — all without code. * Workflow stages let you enforce multi-step approval (Draft > Review > Legal > Published) with role-based gates. If the ask is "editors need approval before publishing," the answer is a workflow, not an app. * Publish rules restrict who can publish to which environment. Roles and permissions give you per-content-type, per-environment, per-locale control. * Automation Hub provides no-code connectors for common triggers — Slack notifications, simple data syncs — without a webhook handler to deploy or monitor. * The core principle: every custom integration adds hosting, monitoring, and maintenance cost that compounds over its lifetime. Configuration has effectively zero ongoing cost. ### 2\. The decision framework * Walk through six levels before writing any code: (1) field validation, (2) workflow stage, (3) publish rule or role, (4) Automation Hub, (5) webhook, (6) custom app. * Each level up the ladder adds maintenance cost. Field validation is free. A custom app requires hosting, monitoring, SDK updates, documentation, and onboarding. * Show the table from the lesson: initial development time, hosting, monitoring, dependency updates, documentation, onboarding, platform upgrades — compare custom app vs webhook vs configuration. * Stress the two-year total cost of ownership lens. A three-day build can cost three hours per quarter to maintain — dependency updates, SDK bumps, deployment fixes. * The worked example: "every blog post needs at least three taxonomy tags before publishing." Walk the framework level by level to show how you land on a lightweight sidebar widget only after configuration falls short. ### 3\. Marketplace apps: browse, install, configure * The Marketplace lives in the left nav of any stack. Two categories: Contentstack-built apps (Algolia, Commercetools, Salesforce, Bynder, Cloudinary) and custom/private apps. * Installing is stack-specific — installing in dev does not install in production. * Walk through installing a pre-built integration: browse the catalog, click Install, review OAuth scopes on the consent screen, configure via the App Configuration page, and the app appears in its defined locations. * Call out concrete examples: Bynder DAM for asset management, Cloudinary for image transformation, Typeform for embedding forms. * Emphasize that pre-built apps are maintained by Contentstack or the vendor — you do not own the maintenance burden. ### 4\. Building custom apps: Developer Hub, App SDK, UI locations * Apps run in sandboxed iframes. Your code is served from your hosting; Contentstack loads it in an iframe and communicates via the App SDK's postMessage bridge. * Six UI locations: Custom Field, Sidebar Widget, Dashboard Widget, Full-Page App, Asset Sidebar, and App Configuration. Each receives different contextual data. * Custom Field: replaces a standard field, owns a JSON value stored in the entry and returned via Delivery API. Think color pickers, product selectors, location pickers. * Sidebar Widget: appears in the right sidebar, reads/modifies the entire entry but does not own a field. Think SEO scorers, translation trackers, quality checklists. * Dashboard Widget: lives on the stack dashboard for at-a-glance info. Think content calendars, publishing feeds, task queues. * Full-Page App: gets its own left-nav item, occupies the full content area. Think analytics dashboards, bulk operations tools, migration interfaces. * RTE Plugin: extends the Rich Text Editor with custom toolbar buttons or content blocks. * App Configuration: the settings UI that stack admins see when installing the app — store API keys, feature toggles, mapping configs here instead of hardcoding. ### 5\. Walk through building a simple custom field or sidebar widget * Start in Developer Hub: create a new app, name it descriptively ("PIM Product Selector," not "Custom Field 1"), select locations, set OAuth scopes. * Scaffold the project: csdx app:create generates a React project with the App SDK pre-installed and location-specific component stubs. * Core pattern: call ContentstackAppSdk.init() (async), get the location-specific interface, read data, render UI, write data back. * For a Custom Field: field.getData() to load, field.setData(value) to save. The JSON you write is exactly what the Delivery API returns. * For a Sidebar Widget: sidebar.entry.getData() reads the full entry, sidebar.entry.onChange() listens for real-time changes. * Test locally: point the location URL in Developer Hub to http://localhost:3000, install in a dev stack, open an entry, see your app in the iframe. * Stress the data contract: whatever JSON shape you write to a Custom Field is consumed by every frontend. Treat it as a versioned API contract — changing it after entries are published breaks consumers. ### 6\. App hosting options: self-hosted vs Contentstack-hosted * Self-hosted: deploy to Vercel, Netlify, AWS S3 + CloudFront, or any static/server hosting. You manage HTTPS, deployment, uptime, and scaling. * Contentstack Launch: Contentstack hosts your app for you. You get HTTPS, deployment, and no infrastructure to manage. This is the path of least resistance for most internal apps. * Trade-off: self-hosted gives you full control (custom domains, edge functions, specific CDN config). Contentstack-hosted removes operational overhead but limits infrastructure customization. * For most certification-level apps and internal tools, Contentstack-hosted is the right default. ### 7\. Webhooks: event-driven integration * Webhooks reverse the API direction: instead of your code calling Contentstack, Contentstack calls your endpoint when something happens. * Configured under Settings > Webhooks. You provide a name, an HTTPS URL, optional custom headers, and select which events trigger it. * Events are organized by resource: entries (create, update, publish, unpublish, workflow), assets (upload, update, delete, publish), content types (create, update, delete), releases (create, deploy). * You can scope to specific content types — a search indexing webhook might only fire on publish/unpublish for Product and Product Line. * Common use cases: search index updates, cache invalidation, notification systems, data sync to commerce/ERP, static site rebuild triggers, audit logging. ### 8\. Show creating a webhook, configuring trigger conditions, and handling the payload * In the UI: Settings > Webhooks > New Webhook. Name it clearly ("Algolia Product Index Update on Publish"). * Select events: check content\_types.entries.publish and content\_types.entries.unpublish. Scope to the Product content type. * Set retry policy: 3-5 retries, 60-second delay. A "failure" is a non-2xx response or timeout. * Walk through the payload structure: event (e.g., content\_types.entries.publish), triggered\_at, triggered\_by, event\_data.entry (the full entry snapshot), event\_data.content\_type, event\_data.environment, event\_data.locale. * Show a real handler: receive the POST, parse the JSON, extract entry data, update the external system. ### 9\. Webhook security: verifying signatures, handling retries, idempotency * Contentstack signs every webhook request and sends signature metadata in headers: X-Contentstack-Request-Signature, X-Contentstack-Request-Timestamp, X-Contentstack-Request-Version. * Your handler fetches the webhook public key from Contentstack's public key endpoint and verifies the signature against the raw request body. * Critical: use the raw request body for verification. If your framework parses JSON first, the bytes change and verification fails. * Validate timestamp freshness to prevent replay attacks. * Idempotency: webhooks are "at least once," not "exactly once." Use a deduplication key (entry UID + event type + timestamp) to skip duplicates. * Respond with 200 immediately, then process asynchronously. If you process synchronously and it takes too long, Contentstack retries, creating duplicates. * For robust async: enqueue the payload to SQS, Pub/Sub, or RabbitMQ and process from a worker. ### 10\. Examples of over-customization and how to avoid it * Character-limit validation app: a team builds a sidebar widget to check meta description length. Contentstack field validation already has min/max character limits. The custom app duplicates built-in functionality and now needs hosting. * Slack notification webhook handler: a developer writes a Node.js Lambda + API Gateway + CloudWatch stack to send a Slack message on publish. Automation Hub does this with a visual connector in under five minutes, no code. * Custom dropdown field: a team builds a Custom Field app for a country dropdown because the list is "dynamic." If the list changes once a year, a Select field with a content model update is cheaper. * Custom workflow engine: a team writes middleware for approval stages, email notifications, and role gates. Contentstack's built-in workflow handles all of this natively. The custom engine creates a parallel system editors must learn. * The pattern: always ask "can built-in features handle this?" before writing code. The answer is "yes" more often than developers expect. ## Screen: What to Show Segment What is on screen Configuration vs customization (items 1-2) Content type builder with field validation settings open. Show a regex validation rule on a SKU field. Then show the Workflow editor with multi-stage approval flow. Decision framework (item 2) Split-screen or overlay graphic showing the six-level ladder: field validation > workflow > publish rule/role > Automation Hub > webhook > custom app. Highlight cost increasing at each level. Marketplace apps (item 3) Contentstack Marketplace catalog in the left nav. Browse the catalog, click into Bynder or Cloudinary, show the install flow, OAuth consent screen, and App Configuration page. Building custom apps (items 4-5) Terminal: run csdx app:create, show the scaffolded project structure. VS Code: open the Custom Field component. Developer Hub: show the app registration with locations and URLs. Contentstack entry editor: show the custom field rendering in the iframe. App hosting (item 6) Developer Hub app settings showing the location URL field. Show switching from localhost:3000 to a Contentstack Launch deployed URL. Webhooks (items 7-8) Settings > Webhooks in the Contentstack UI. Create a new webhook, select events, scope to a content type. Then show the webhook logs with delivery attempts and status codes. Webhook handler code (items 8-9) VS Code with the Express handler open. Walk through the signature verification block, the immediate 200 response, and the async processing function. Highlight the deduplication key pattern. Over-customization (item 10) Side-by-side: left shows the custom app code and deployment config, right shows the equivalent built-in feature configured in under a minute. Make the contrast visual and obvious. ## Veda Scenario Thread Veda (the fictional jewelry brand) runs through this video as the connective tissue: * **Configuration first:** Veda's content team asks for SKU validation on product entries. Show configuring a regex rule (^VDA-\[A-Z0-9\]{4}-\[A-Z0-9\]{2}$) directly in the content type builder — no code, done in 30 seconds. * **Marketplace app:** Veda uses Bynder for digital asset management. Show browsing the Marketplace, installing the Bynder app, and configuring it so editors can search Bynder assets from within entries. * **Custom app:** Veda's editors need to pull product data from their PIM system into entries. No marketplace app exists for their PIM. Show registering a Custom Field app in Developer Hub, scaffolding with the CLI, and building a product selector that queries the PIM API and writes structured JSON to the entry field. * **Webhook:** when a Veda product is published, the search index needs updating. Show creating a webhook scoped to the Product content type's publish event, pointing to an Algolia update handler, and walking through the handler code. * **Webhook security:** show verifying the webhook signature in the handler so only legitimate Contentstack requests trigger index updates. * **Over-customization check:** Veda's dev team proposes building a custom sidebar widget to warn when meta descriptions exceed 160 characters. Pause and show that field validation already handles this — cancel the custom build and configure the character limit instead. ## Transitions 1. **Intro to configuration:** "Before we write any code, let's look at how much Contentstack handles out of the box." 2. **Configuration to decision framework:** "So configuration covers a lot — but how do you know when it is not enough? That is where the decision framework comes in." 3. **Decision framework to Marketplace apps:** "If configuration falls short, the next question is: has someone already built what you need?" 4. **Marketplace apps to custom apps:** "When the Marketplace does not have what you need, you build it yourself — and Contentstack gives you a clean developer workflow for that." 5. **Custom app walkthrough to hosting:** "You have got a working app locally — now where does it live in production?" 6. **Hosting to webhooks:** "Apps handle the UI side. For server-side reactions to content events, you use webhooks." 7. **Webhook creation to webhook security:** "A working webhook is step one. A secure webhook is the real requirement." 8. **Webhook security to over-customization:** "Now that you know how to build all of this, here is the most important skill: knowing when not to." 9. **Over-customization to closing:** "Every customization is a commitment. Use the decision framework, start with configuration, and only build what you genuinely need to own." 10. **Closing to Video 12:** "In the next video, we move from extending the platform to deploying what you have built — hosting, environments, and release management with Contentstack Launch." ## Common Mistakes to Call Out 1. **Jumping straight to code without evaluating configuration.** The most frequent error. Every customization decision should start with "can built-in features handle this?" and only proceed to code when the answer is definitively no. Show the decision framework ladder and make viewers internalize the habit. 2. **Forgetting to call** **ContentstackAppSdk.init()** **before accessing data.** The SDK initialization is asynchronous. Accessing sdk.location before init() resolves produces undefined values and silent failures. Gate your UI rendering on initialization completing. 3. **Requesting excessive OAuth scopes.** An app that only reads entry data should not request write scopes. Follow the principle of least privilege — excessive scopes trigger security concerns and may cause admins to reject the install. 4. **Assuming all app locations have the same context.** A Sidebar Widget has entry.getData(). A Dashboard Widget does not — there is no "current entry" on the dashboard. Always check which location is active before calling location-specific methods. 5. **Changing a Custom Field's JSON shape after entries are published.** The data your Custom Field writes is consumed directly by frontend applications via the Delivery API. Changing that shape breaks every consumer. Treat it as a versioned API contract. 6. **Processing webhooks synchronously before responding 200.** If your handler does a database write, an API call, and a cache purge before responding, any step can time out. Contentstack retries, and you get duplicates. Respond immediately, process async. 7. **Skipping webhook signature verification.** Without verifying request signatures, your endpoint accepts requests from any source. An attacker who discovers the URL could trigger index deletions, cache purges, or data corruption. 8. **Not accounting for duplicate webhook deliveries.** Webhooks are "at least once," not "exactly once." Without idempotent processing using a deduplication key, duplicate deliveries create duplicate records or repeated side effects. 9. **Hardcoding stack-specific values in app code.** API keys, content type UIDs, environment names, and service URLs belong in App Configuration, not in your source code. The same app should work across stacks without modification. 10. **Building for imagined future requirements.** "We might need a PIM integration someday" is not a reason to build one today. Apply YAGNI — build when the requirement is concrete and funded, not hypothetical. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 11 — When To Customize: Configuration vs Apps vs Webhooks** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 27 — Video Production Plan : Video 12 — Maintainability, Governance, and Long-Term Ownership #### Lesson text # Video 12 — Maintainability, Governance, and Long-Term Ownership Attribute Details Course 6 (Extending and Customizing Contentstack), Module 6.2 Covers Lessons 6.2.1, 6.2.2, 6.2.3 Priority Polish Length 12-18 min Format Slides + talking head (more conceptual) Status Not started ## Why This Video Matters This is where the platform shifts from implementation to stewardship. Most platform pain appears after launch, not during the initial build. ## Outline 1. Designing for maintainability: future-you (or your replacement) will inherit every decision you make today 2. Documentation that actually helps: document the "why", not just the "what" 3. Technical debt in CMS context: unused content types, orphaned fields, undocumented webhooks, custom apps with no owner 4. Monitoring webhook health and app dependencies 5. Governance enables velocity: naming conventions, review processes, ownership assignments 6. Audit checklist: what to review quarterly 7. Runbooks and operational ownership ## Key Lines "Most platform pain appears after launch, not during the initial build." "Reliability patterns are part of the design, not an afterthought." "The best CMS implementations are boring. They just work, year after year." ## Detailed Talking Points ### 1\. Designing for maintainability: future-you inherits every decision * Open with the core truth: the webhook handler you deploy today will still be running eighteen months from now, long after you have forgotten why you made specific choices. Future-you, or whoever replaces you, reads your code with zero context. * Single responsibility for integrations: one handler does one thing. Three 200-line handlers beat one 3,000-line "platform." When the Algolia indexer needs a change, you touch one directory. Slack notification breaks? Different directory. Failures stay isolated. * Show the folder structure contrast: three focused handler directories versus the monolithic "integration platform" with its routing config, adapter abstractions, middleware layers, and admin UI. Same three requirements, ten times the code. * YAGNI is your friend. Do not build a generic webhook framework when you need three specific handlers. Do not wrap the App SDK in "your custom SDK wrapper" -- that just forces the next developer to learn two APIs instead of one. * Naming is the cheapest form of documentation. "webhook-handler-2" tells you nothing. "algolia-product-index-on-publish" tells you everything without opening a file. Apply this to webhooks, endpoints, environment variables, handler functions, config files. * Dependency management matters: every npm package is a maintenance commitment. Security patches, breaking changes, abandoned maintainers, supply chain risk. A webhook handler that calls one API does not need lodash, moment, axios, and an ORM. * Pin your versions. Commit lockfiles. Schedule monthly or quarterly dependency reviews. ### 2\. Documentation that actually helps: document the "why" * The code explains the what. Documentation should explain the why -- the business requirement, the design decision, the thing that disappears when the original developer leaves. * Every integration needs a README answering five questions: What does it do? Why does it exist? How do I deploy it? What Contentstack settings does it depend on? How do I troubleshoot it? * Content model documentation is not about listing fields -- the UI already shows that. Document the reasoning: why author is a Reference field instead of a Group field, why body uses JSON RTE instead of Markdown, why legacy\_promo\_banner still exists and when it can be removed. * Decision records prevent repeated debates. When you choose JSON RTE over Markdown, write down why so the next developer does not re-litigate the decision. * Webhook routing documentation: a single table showing every webhook, its events, target content types, handler URL, and owner. Without this, understanding the integration landscape requires clicking through every webhook in the Contentstack UI. * Environment topology documentation: which environments serve which frontends, which tokens are in use, where tokens are stored. One page that a new developer reads on day one. ### 3\. Technical debt in CMS context * Technical debt in CMS projects is sneaky. Nobody files a ticket saying "our webhook handler is now unmaintainable." It accumulates entry by entry, dependency by dependency, undocumented decision by undocumented decision. * Content type debt: fields added for a campaign, used once, never removed. legacy\_banner\_text sitting in Article with no validation, no documentation, no entries using it -- but nobody deletes it because "something might depend on it." * Orphaned content types created for features that never launched. Inconsistent field naming across types -- hero\_image here, banner\_image there, main\_image somewhere else. * Integration debt: webhook handlers nobody understands, custom apps on unmaintained framework versions, hardcoded stack UIDs and content type UIDs, undocumented Automation Hub flows. * Configuration drift: the README says one thing, the deployed environment says another. Deployment docs reference a CI/CD pipeline that was replaced three months ago. * The bus factor problem: if the developer who built the Algolia webhook handler is unavailable tomorrow, can someone else debug a delivery failure, deploy a fix, and verify the index? If the answer is no, your bus factor is one. ### 4\. Monitoring webhook health and app dependencies * Without monitoring, failures are silent. Your search index drifts out of sync, Slack notifications stop, cache purges stop working, and nobody notices until an editor reports stale content. * Every handler needs error tracking (Sentry, Datadog, or equivalent). Every unhandled error should trigger an alert. * Health checks: expose a GET /health endpoint, monitor it with an uptime service. * Webhook delivery monitoring: regularly check the webhook logs in Contentstack UI under Settings > Webhooks > \[Webhook Name\] > Logs. Look for non-200 status codes. * A 50-line handler can fail just as silently as a 5,000-line application. Monitoring is proportional to impact, not to code complexity. ### 5\. Governance enables velocity: naming conventions, review processes, ownership * Governance has a reputation problem. Developers hear it and think approval committees and two-week lead times. But the absence of governance creates a different kind of slow: conflicting content type changes, scattered tokens, orphaned webhooks, production publishes that break frontends. * Good governance answers: "who can do what, and how do we stay coordinated?" When those agreements are clear, teams move faster. * Content type governance: content type changes are schema changes. Adding a field changes the API response for every entry. Removing a field can break frontends. Renaming a field UID breaks every query referencing it. * Token governance: delivery tokens in environment variables, never in client-side code. Management tokens exclusively in a secrets manager. Rotate management tokens quarterly and immediately when someone leaves. * Use Contentstack roles to enforce governance automatically. Restrict production publish to specific roles. Junior editors publish to staging only. Do not rely on people remembering policies. * When governance becomes a bottleneck: if field additions take more than one business day, if developers avoid proposing improvements, if the process has more steps than the actual work -- loosen it. ### 6\. Audit checklist: what to review quarterly * Run a quarterly audit of every custom integration: 30 to 60 minutes with a structured checklist. * Ownership: who maintains this? If they left tomorrow, could someone else take over? Is the owner documented? * Dependencies: are they current? Any deprecated or abandoned? Run npm audit for known vulnerabilities. * Tests: do they still pass? Do they cover current behavior, or have features been added without test updates? * Deployment: is the process documented? Can a new team member deploy without asking the original developer? * Contentstack configuration: does the webhook config still match the handler's expected events? Has the content type schema changed? * Monitoring: is error alerting active? Check webhook logs for delivery failures. Has anyone looked at the dashboards this quarter? * Prioritize findings: security findings first, silent failures next, documentation gaps this quarter, technical improvements when capacity allows. ### 7\. Runbooks and operational ownership * A runbook tells you exactly what to do when something goes wrong. Unlike documentation that explains how things work, a runbook is a step-by-step procedure for a specific scenario. * Runbook for re-triggering a failed webhook: navigate to webhook logs, find the failed delivery, copy the payload, verify the handler is healthy, replay with curl including signature headers, verify processing. * Runbook for reindexing search after bulk publish: verify the bulk publish is complete, run the full reindex script with the right environment variables, verify the index record count. * Runbook for deploying a new Marketplace app version: pre-deployment checklist (tests pass, tested in dev stack, SDK compatible, no breaking data format changes), build, deploy, verify in the Contentstack UI, know your rollback path. * Runbooks raise the bus factor. When the procedure is written down, anyone on the team can handle the incident. ## Screen: What to Show * **Outline item 1 (Maintainability):** Show the focused handler folder structure side-by-side with the monolithic "integration platform" folder structure. Highlight the line counts and file counts. If possible, show a real handler file under 200 lines to demonstrate how readable a focused handler is. * **Outline item 2 (Documentation):** Show an example integration README with the five-question structure filled in. Show a content model decision record for the Article content type. Show a webhook routing table in Markdown. * **Outline item 3 (Technical debt):** In the Contentstack UI, navigate to a content type with deprecated fields (or a mock one). Point at fields that look abandoned. Show the content type list and highlight types that might be orphaned. Show the webhook list with poorly named webhooks like "My Webhook" or "Handler 3." * **Outline item 4 (Monitoring):** Show the Contentstack webhook logs screen (Settings > Webhooks > \[Webhook Name\] > Logs). Point at delivery status codes. Show what a failed delivery looks like versus a successful one. Briefly show a Sentry or Datadog error dashboard for a handler. * **Outline item 5 (Governance):** Show the Contentstack Roles screen with a custom role configuration. Show publish rules under Settings > Publish Rules. Show the environment list and explain the mapping to frontends. * **Outline item 6 (Audit):** Show the audit checklist as a document or checklist template. Walk through one integration as a live audit example -- check ownership, dependencies, tests, deployment docs, monitoring. * **Outline item 7 (Runbooks):** Show a runbook document. Walk through the "re-trigger a failed webhook" runbook step by step, showing each screen in the Contentstack UI as you go. ## Veda Scenario Thread Veda has been building custom integrations throughout the course: webhook handlers for Algolia indexing, a PIM Product Selector Marketplace app, Automation Hub flows for notifications. Now she faces the reality that these integrations need to survive beyond her involvement. * **Maintainability:** Veda refactors her monolithic webhook handler into three focused handlers -- one for product indexing, one for Slack notifications, one for CDN cache purging. She applies descriptive naming to each webhook in the Contentstack UI. * **Documentation:** Veda writes READMEs for each handler using the five-question template. She documents why the product content type uses a Reference field for brand instead of embedding it. She creates a webhook routing table covering all of Veda Jewelry's integrations. * **Technical debt:** Veda runs an audit and discovers a legacy\_promo\_banner field on the Article content type from a campaign six months ago, two orphaned webhooks pointing at a decommissioned staging URL, and an Automation Hub flow that nobody remembers creating. She cleans them up. * **Monitoring:** Veda adds error tracking to each handler and sets up health check monitoring. She catches a silent failure in the CDN cache purge handler that had been failing for two weeks without anyone noticing. * **Governance:** Veda establishes lightweight governance for her growing team: content type changes proposed in a Slack channel, production webhooks require a brief review, management tokens stored in AWS Secrets Manager with quarterly rotation. * **Audit and runbooks:** Veda creates the quarterly audit checklist and writes runbooks for the three most common operational scenarios: re-triggering a failed webhook, reindexing Algolia after a bulk publish, and deploying a new version of the PIM Product Selector app. The thread shows Veda transitioning from builder to steward -- the integrations she built now have documentation, monitoring, ownership, and operational procedures that let her team handle incidents without depending solely on her. ## Transitions 1. **Opening to Item 1 (Maintainability):** "Building integrations is the easy part -- keeping them running and understandable twelve months later is where most teams struggle, so let's start with what maintainable code actually looks like in Contentstack." 2. **Item 1 to Item 2 (Documentation):** "Clean code structure gets you halfway there, but without documentation that explains the decisions behind the code, the next developer is still guessing." 3. **Item 2 to Item 3 (Technical debt):** "Even with good docs, debt accumulates -- let's look at the specific forms it takes in CMS projects and how to spot it before it becomes critical." 4. **Item 3 to Item 4 (Monitoring):** "Identifying debt is reactive -- monitoring lets you catch problems as they happen instead of discovering them during an audit." 5. **Item 4 to Item 5 (Governance):** "Monitoring tells you when things break, but governance prevents the conditions that cause breakage in the first place." 6. **Item 5 to Item 6 (Audit):** "Governance sets the rules -- the quarterly audit is how you verify the rules are being followed and the platform is still healthy." 7. **Item 6 to Item 7 (Runbooks):** "The audit finds problems, but when something breaks at 2 AM, you need a runbook that tells you exactly what to do without thinking." 8. **Closing to Video 13:** "You now know how to keep your platform healthy over time -- in the next video, we wrap the entire course with a review and point you toward the certification exam." ## Common Mistakes to Call Out * **Building abstractions too early.** The rule of three applies: do not extract a framework until you have three concrete cases sharing a pattern. Two webhook handlers do not justify a webhook framework. * **Treating "it might change" as a reason to add configuration.** If the Algolia index name has been "products" for two years, hardcode it. Add configuration when the value actually needs to vary, not before. Every config option is a decision the next developer must understand. * **Skipping monitoring because the integration is "simple."** A 50-line handler fails just as silently as a 5,000-line app. If the handler stops working, content and search drift apart, and the problem compounds with every publish. * **Documenting everything at the wrong level of detail.** A 50-page document explaining every line of code is as useless as no documentation. Document the why, the how-to-deploy, and the how-to-troubleshoot. The code explains the what. * **Treating technical debt as something to fix "when we have time."** Teams never have time. Debt compounds. A field that should have been removed six months ago now has entries using it by accident. Allocate explicit, recurring capacity -- one hour per week, one day per sprint, or a quarterly cleanup day. * **Assuming the Contentstack UI is sufficient documentation for webhook routing.** The UI shows individual configs but not the full picture of how all webhooks, automations, and external integrations interact. Write the routing table. * **Applying uniform governance to all stacks.** Development stacks are sandboxes -- let developers experiment. Production stacks need tighter controls. Differentiate governance by stack purpose. * **Governing content creation instead of infrastructure.** Editors do not need permission to create entries. Governance applies to content types, webhooks, tokens, environments, and app installations -- the things that affect platform structure and reliability. * **Management tokens in** **.env** **files or shared via Slack.** A single leaked management token grants full read-write access. Store them exclusively in a secrets manager and rotate immediately when someone with access leaves. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 12 — Maintainability, Governance, and Long-Term Ownership** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ### Lesson 28 — Video Production Plan : Video 13 — Contentstack in a Composable DXP #### Lesson text # Video 13 — Contentstack in a Composable DXP Attribute Details Course 7 (Integrations and the Composable DXP) Covers Lessons 7.1.1, 7.1.2, 7.1.3, 7.2.1, 7.2.2, 7.2.3 Priority Polish Length 15-22 min Format Slides/diagrams + demos where possible Status Not started ## Why This Video Matters Strong closing video that helps learners place Contentstack inside a broader architecture. Zooms out from implementation details to system-level thinking. ## Outline 1. CMS as system of record: Contentstack owns content; other systems own commerce, search, analytics, auth 2. Draw the boundary: what lives in the CMS vs what lives in external systems 3. Integration patterns: event-driven (webhooks), API-mediated (pull), middleware/orchestration layer, batch 4. When to use each pattern — decision framework based on latency needs, data volume, and coupling tolerance 5. Contentstack Launch: hosting and deployment platform — when to use it vs Vercel/Netlify/custom hosting 6. Show a deployment flow: content publish triggers build, build deploys to hosting 7. Automate and Personalize: built-in tools for content automation and audience targeting 8. AI-assisted workflows: how AI features integrate into the editorial process 9. The developer role in AI-enabled operations 10. Where the platform is heading: composable DXP, MACH architecture ## Key Lines "Composable does not mean everything belongs everywhere." "System boundaries are one of the most important architecture decisions in a CMS implementation." "AI changes the workflow, but it does not remove developer responsibility." ## Detailed Talking Points ### 1\. CMS as system of record * Contentstack is the system of record for content — editorial text, images, structured data that content teams create and manage through a publish workflow. * Commerce platforms own pricing, inventory, and transactions. Search platforms own indexes. Analytics platforms own behavioral data. Auth systems own user identity. * The core question: who creates and maintains this data? If editors create it through an editorial workflow, it belongs in the CMS. If it is system-generated, transactional, or changes faster than editorial workflows can accommodate, it belongs elsewhere. * Show the decision framework table: product descriptions (CMS), product prices (commerce), inventory (ERP), blog articles (CMS), user profiles (auth), session data (app server). * "Every content platform eventually becomes a dumping ground if nobody draws clear boundaries." ### 2\. Draw the boundary: CMS vs external systems * Walk through a concrete retail example: Contentstack holds product marketing pages, category landing pages, blog articles, navigation, promotional banners. Shopify holds variants, SKUs, pricing, cart, checkout, customer accounts. ERP holds purchase orders, fulfillment, returns. * The connection between systems is a shared identifier — a shopify\_handle or sku field in Contentstack that links editorial content to the commerce product. It does not create a live connection; the frontend uses it to correlate data at render time. * Explain the hybrid composition pattern: the frontend fetches editorial content from Contentstack and transactional data from external APIs, combining them at render time. Each system stays authoritative for its own data. * Stress ownership clarity: if it is unclear who owns a piece of data, that is a design problem you need to solve before writing any code. ### 3\. Integration patterns * Three patterns cover virtually all CMS integrations: event-driven (webhooks), API-mediated (runtime composition), and batch sync (scheduled jobs). They are complementary, not competing. * Event-driven: Contentstack fires an HTTP POST when something happens (entry published, workflow stage changed). Your handler reacts — updates a search index, invalidates a cache, sends a notification. * API-mediated: the frontend calls multiple APIs at render time and composes them into a single page. No data is copied between systems. Each system remains authoritative. * Batch sync: a scheduled process reads data from a source, transforms it, and writes it to a target. Useful for large data volumes, initial loading, systems that do not support events. * Most real projects use all three for different integration points within the same architecture. ### 4\. When to use each pattern — decision framework * Three factors drive the choice: how quickly the target needs to reflect changes, how much data moves, and whether the source supports events. * Search index must reflect changes within seconds → event-driven (webhooks fire immediately on publish). * Product page combines CMS content with live pricing → API-mediated (prices change independently, no copying). * 10,000 products need loading from a PIM → batch sync (bulk data, tolerance for latency). * Walk through the decision matrix on screen. Latency needs, data volume, coupling tolerance. * Call out the error handling differences: dead-letter queues for events, Promise.allSettled for runtime composition, checkpoint-based resumption for batch jobs. * Design webhook handlers to be idempotent — processing the same event twice must produce the same result. ### 5\. Contentstack Launch * Launch is Contentstack's built-in hosting platform: Git-based deployments, CDN distribution, content-triggered rebuilds, all from the CMS dashboard. * Git-connected: push to a branch, Launch builds and deploys. Supports Next.js, Nuxt, Astro, Gatsby, static generators, and SPAs. * Environment mapping: staging branch deploys to staging, main branch deploys to production. Each deployment uses the delivery token scoped to its Contentstack environment. * Auto-deploy on content publish: when an editor publishes, Launch rebuilds the associated deployment. This is valuable for SSG sites but redundant for SSR apps that fetch content on every request. * Environment variables with secrets support — tokens are encrypted, not visible after saving. * Preview URLs: editors get a .contentstacklaunch.com subdomain to verify before attaching a custom domain. ### 6\. Deployment flow demo * Walk through the end-to-end flow: editor publishes content → Contentstack detects mapped Launch deployment → Launch queues a build from the configured branch → build fetches latest content from Delivery API → new build deploys to CDN. * Show the two-environment setup: staging and production with different branches, different tokens, different custom domains. * Explain that Launch auto-injects Contentstack credentials as environment variables, reducing manual credential management. * Mention custom domains with automatic SSL provisioning via Let's Encrypt. ### 7\. Automate and Personalize * Automate is a visual flow builder for connecting Contentstack with external services without writing custom code. Triggers, conditions, actions, loops — all configured visually. * Distinguish from Automation Hub: Automation Hub handles internal CMS actions (notify editor on workflow change). Automate handles cross-system orchestration (Jira + Slack + Salesforce in one flow). * Distinguish from raw webhooks: webhooks are point-to-point and require you to build error handling, retry logic, and data transformation. Automate provides these out of the box with pre-built connectors. * Personalize: editors create content variants within a single entry (enterprise banner, free-tier banner, anonymous banner). Audience rules are defined in Personalize. The SDK resolves the correct variant at runtime. * The frontend renders whatever content Personalize resolves — no if (user.plan === 'enterprise') logic in your code. Audience rules are externalized so marketing can adjust targeting without code deployments. * Default variant serves as fallback when no audience rule matches. ### 8\. AI-assisted workflows * AI-generated content follows the same schema, workflows, and API contracts as human-written content. Your frontend needs zero special handling. * Built-in features: Brand Kit for voice/tone consistency, AI-assisted content generation within the editor, AI-powered content suggestions. * Custom integrations: use webhooks and the CMA to build pipelines — auto-generate summaries on entry creation, auto-tag with taxonomy terms, generate image alt text. * The AI content pipeline: creation (AI draft) → human review → enrichment (AI tagging, summarizing) → human approval → publish → delivery. * Every AI pipeline should terminate at a human review step before content reaches the Delivery API. AI assists editors; it does not replace editorial judgment. * Trigger AI processing at meaningful lifecycle points (entry creation, workflow stage changes), not on every field save — otherwise you burn through API costs. ### 9\. The developer role in AI-enabled operations * AI changes where you spend time, not whether you are needed. Content modeling, frontend dev, integration architecture — these remain your core responsibilities. * New responsibilities: building AI processing pipelines, evaluating AI providers (quality, latency, cost, data residency), implementing output validation, building feedback loops. * Guardrails: validate AI output before writing it back to Contentstack. Check format, length, allowed values. AI output is probabilistic, not deterministic. * Design content models with separate fields for AI suggestions and human-authored content so editors can compare and choose. Do not silently overwrite editor fields. * Build cost monitoring and acceptance tracking from the start. Without measurement, you cannot tell if AI integrations deliver value. * Security: sending content to external AI services means content leaves your infrastructure. Filter sensitive content types, check provider data policies, respect data residency requirements. ### 10\. Where the platform is heading + series wrap-up * Composable DXP means each system does what it does best. The CMS owns content. Commerce owns transactions. Search owns indexing. AI owns enrichment. The frontend composes them all. * MACH architecture (Microservices, API-first, Cloud-native, Headless) is the underlying philosophy. Contentstack fits naturally because it is API-first and headless by design. * Connect back to the full journey: Video 1 started with what Contentstack is and how headless CMS works. We progressed through content modeling, environments, the SDK and Delivery API, Live Preview, workflows, extensions, webhooks, and now the full composable picture. * The certification validates that you can design content models, build frontends, integrate external systems, deploy and host, and make architectural decisions about where data lives. * Close with: "You now have the toolkit to build production-grade content architectures. The rest is building." ## Screen: What to Show Outline item What to show on screen 1\. CMS as system of record Diagram: Contentstack at center with arrows to Commerce, Search, Analytics, Auth as separate boxes. Show the decision framework table from lesson content. 2\. Draw the boundary Split-screen diagram: left side "In Contentstack" (marketing pages, navigation, banners), right side "In Shopify/ERP" (pricing, inventory, orders). Show a JSON snippet of a product entry with shopify\_handle field. 3\. Integration patterns Architecture diagram showing three lanes: webhooks (event arrow from CMS to search index), API-mediated (frontend pulling from CMS + commerce + reviews), batch sync (cron job arrow from PIM to CMS). 4\. Decision framework Show the decision matrix table on screen: requirement → pattern → why. Walk through each row. 5\. Contentstack Launch Contentstack dashboard: Launch section. Show the deployment creation flow — connect repo, pick branch, set env vars. Show a live deployment URL. 6\. Deployment flow Diagram: editor publishes → Launch rebuilds → CDN serves. Show the two-environment table (staging vs production branches, tokens, domains). If time allows, trigger an actual content publish and show the build kicking off. 7\. Automate and Personalize Automate: show the visual flow builder with a trigger → condition → action chain. Personalize: show an entry with multiple variants in the editor, then show the SDK code that resolves the variant. 8\. AI-assisted workflows Show the AI content pipeline diagram (creation → review → enrichment → approval → publish → delivery). Show a code snippet of a webhook handler that calls an AI service and writes back via the CMA. 9\. Developer role in AI Show the AI guardrails code: tag validation function, cost tracking snippet. Show a content model with parallel fields (human-authored seo\_title vs AI-suggested suggested\_seo\_title). 10\. Platform direction + wrap-up Full composable architecture diagram with all pieces labeled. Then a recap slide connecting all 13 videos in the series — a visual journey map. ## Veda Scenario Thread Veda has been the throughline for the entire series. In this closing video, bring her story full circle: * **System of record:** Veda's travel platform uses Contentstack for destination descriptions, travel guides, and campaign content. Amadeus owns tour pricing and availability. A reviews platform owns user-generated ratings. The boundaries are clear because Veda drew them early. * **Integration patterns:** Veda uses all three patterns simultaneously — webhooks to update Algolia when destinations are published, API-mediated composition to show live tour prices alongside editorial content, and a nightly batch sync to import new photography from the DAM into Contentstack. * **Launch:** Veda deploys her Next.js frontend on Contentstack Launch with staging and production environments. When an editor publishes a new destination to staging, Launch rebuilds automatically and the team reviews at staging.veda-travel.com. * **Automate:** When a destination entry is approved, an Automate flow creates a Jira ticket for the partnerships team, posts to the #new-destinations Slack channel, and updates a Salesforce record — all without custom code. * **Personalize:** Veda's homepage shows different hero banners: returning visitors see personalized destination recommendations, first-time visitors see a general brand story, and visitors from partner referrals see co-branded messaging. The frontend code is identical for all visitors. * **AI workflows:** Veda's content team uses AI to draft destination summaries and auto-generate SEO metadata. A webhook triggers AI enrichment when entries reach the "Ready for Review" stage. Editors review AI suggestions alongside their own content before publishing. * **Wrap-up:** Veda started the series learning what Contentstack is. Now she is architecting a composable platform where the CMS is one piece of a larger system. That is the developer journey this certification represents. ## Transitions 1 → 2: "Now that we know Contentstack owns content and only content, let us draw the exact boundary for a real project." 2 → 3: "With boundaries drawn, the question becomes: how do these systems actually talk to each other?" 3 → 4: "Three patterns, three sets of trade-offs — so how do you pick the right one for a given integration point?" 4 → 5: "Once your content is integrated and your frontend is built, you need somewhere to host and deploy it." 5 → 6: "Let us walk through what this deployment flow actually looks like end to end." 6 → 7: "Beyond hosting, Contentstack gives you two more tools that extend the platform: Automate for workflow orchestration and Personalize for audience targeting." 7 → 8: "The newest layer in this stack is AI — and it plugs into the same editorial workflow we have been building throughout this series." 8 → 9: "AI changes the workflow, but it does not change your job title. Let us talk about what the developer actually owns in an AI-enabled CMS." 9 → 10: "We have covered the full composable picture. Let us zoom out one last time and put it all together." **Series closing wrap-up:** "This is where the series ends — but it is also where your work begins. Over thirteen videos, we went from understanding what a headless CMS is, to modeling content, to building frontends with the SDK, to Live Preview, workflows, extensions, webhooks, and now the full composable architecture. You have seen how Contentstack fits into a broader system, how to integrate it with commerce, search, AI, and deployment platforms, and how to make the architectural decisions that separate a working implementation from a well-designed one. The certification exam tests whether you can apply all of this. You are ready. Go build something." ## Common Mistakes to Call Out 1. **Storing pricing or inventory in the CMS.** Prices change with flash sales, regional rules, and dynamic algorithms. Inventory changes with every purchase. Neither follows an editorial workflow. The moment an editor publishes, the data is stale. Keep transactional data in the commerce platform and fetch it at render time. 2. **Using the CMS as a configuration store.** Storing API endpoints, feature flags, or redirect rules as Contentstack entries clutters the editorial interface with non-content data. Editors see content types they should not touch. Use environment variables or dedicated configuration services. 3. **Polling for changes instead of using webhooks.** A cron job that checks every 5 minutes whether content changed wastes resources and still has latency. Webhooks fire immediately on publish — use event-driven integration when you need near-real-time reactions. 4. **Copying external data into Contentstack instead of composing at runtime.** Syncing product prices into CMS fields every hour creates staleness, a single point of failure (the sync job), and forces editors to see data they should not manage. Use API-mediated composition at render time. 5. **Ignoring error handling in webhook endpoints.** A handler that returns 200 without checking downstream success silently loses events. If Algolia or Slack is down, the event is acknowledged and gone forever. Build idempotent handlers with dead-letter queues. 6. **Enabling auto-deploy for SSR applications.** If your app uses getServerSideProps exclusively, every content publish triggers a full rebuild that accomplishes nothing — SSR already fetches fresh content on each request. Auto-deploy is for static generation only. 7. **Using the same delivery token for staging and production Launch deployments.** Both deployments end up fetching from the same environment, so staging never shows draft or staged content. Each deployment must use the token scoped to its corresponding Contentstack environment. 8. **Hardcoding personalization logic in the frontend.** Writing if (user.plan === 'enterprise') scatters targeting rules across the codebase and requires code deployments to change them. Use Personalize to externalize audience rules so marketing can adjust targeting independently. 9. **Publishing AI-generated content without human review.** Bypassing workflow stages removes the editorial safety net and risks putting hallucinated, inaccurate, or off-brand content live. Every AI pipeline should terminate at a human review step. 10. **Treating AI integration as only a prompt engineering problem.** Neglecting error handling, output validation, cost monitoring, and feedback loops leads to pipelines that work in testing but fail unpredictably in production. AI integration is systems engineering. ## Notes Use this space for recording notes, script drafts, or post-production feedback. #### Key takeaways - Connect **Video Production Plan : Video 13 — Contentstack in a Composable DXP** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ## Resources & references | Page | Companion Markdown | | --- | --- | | /courses/video-production-plan/video-production-plan-overview | /academy/md/courses/video-production-plan/video-production-plan-overview.md | | /courses/video-production-plan/video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call | /academy/md/courses/video-production-plan/video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call.md | | /courses/video-production-plan/video-production-plan-video-2-headless-foundations-and-designing-for-editors | /academy/md/courses/video-production-plan/video-production-plan-video-2-headless-foundations-and-designing-for-editors.md | | /courses/video-production-plan/video-production-plan-video-3-structured-content-and-api-contracts | /academy/md/courses/video-production-plan/video-production-plan-video-3-structured-content-and-api-contracts.md | | /courses/video-production-plan/video-production-plan-video-4-composition-query-performance-and-modeling-in-practice | /academy/md/courses/video-production-plan/video-production-plan-video-4-composition-query-performance-and-modeling-in-practice.md | | /courses/video-production-plan/video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice | /academy/md/courses/video-production-plan/video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice.md | | /courses/video-production-plan/video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk | /academy/md/courses/video-production-plan/video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk.md | | /courses/video-production-plan/video-production-plan-video-7-performance-images-environments-and-cli-migrations | /academy/md/courses/video-production-plan/video-production-plan-video-7-performance-images-environments-and-cli-migrations.md | | /courses/video-production-plan/video-production-plan-video-8-live-preview-architecture-and-preview-routing | /academy/md/courses/video-production-plan/video-production-plan-video-8-live-preview-architecture-and-preview-routing.md | | /courses/video-production-plan/video-production-plan-video-9-visual-builder-releases-and-future-state-preview | /academy/md/courses/video-production-plan/video-production-plan-video-9-visual-builder-releases-and-future-state-preview.md | | /courses/video-production-plan/video-production-plan-video-10-workflow-automation-hub-and-branch-strategy | /academy/md/courses/video-production-plan/video-production-plan-video-10-workflow-automation-hub-and-branch-strategy.md | | /courses/video-production-plan/video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks | /academy/md/courses/video-production-plan/video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks.md | | /courses/video-production-plan/video-production-plan-video-12-maintainability-governance-and-long-term-ownership | /academy/md/courses/video-production-plan/video-production-plan-video-12-maintainability-governance-and-long-term-ownership.md | | /courses/video-production-plan/video-production-plan-video-13-contentstack-in-a-composable-dxp | /academy/md/courses/video-production-plan/video-production-plan-video-13-contentstack-in-a-composable-dxp.md | | /courses/video-production-plan/video-production-plan-overview | /academy/md/courses/video-production-plan/video-production-plan-overview.md | | /courses/video-production-plan/video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call | /academy/md/courses/video-production-plan/video-production-plan-video-1-start-here-certification-roadmap-and-first-api-call.md | | /courses/video-production-plan/video-production-plan-video-2-headless-foundations-and-designing-for-editors | /academy/md/courses/video-production-plan/video-production-plan-video-2-headless-foundations-and-designing-for-editors.md | | /courses/video-production-plan/video-production-plan-video-3-structured-content-and-api-contracts | /academy/md/courses/video-production-plan/video-production-plan-video-3-structured-content-and-api-contracts.md | | /courses/video-production-plan/video-production-plan-video-4-composition-query-performance-and-modeling-in-practice | /academy/md/courses/video-production-plan/video-production-plan-video-4-composition-query-performance-and-modeling-in-practice.md | | /courses/video-production-plan/video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice | /academy/md/courses/video-production-plan/video-production-plan-video-5-api-architecture-authentication-and-query-surface-choice.md | | /courses/video-production-plan/video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk | /academy/md/courses/video-production-plan/video-production-plan-video-6-fetching-and-rendering-content-with-the-sdk.md | | /courses/video-production-plan/video-production-plan-video-7-performance-images-environments-and-cli-migrations | /academy/md/courses/video-production-plan/video-production-plan-video-7-performance-images-environments-and-cli-migrations.md | | /courses/video-production-plan/video-production-plan-video-8-live-preview-architecture-and-preview-routing | /academy/md/courses/video-production-plan/video-production-plan-video-8-live-preview-architecture-and-preview-routing.md | | /courses/video-production-plan/video-production-plan-video-9-visual-builder-releases-and-future-state-preview | /academy/md/courses/video-production-plan/video-production-plan-video-9-visual-builder-releases-and-future-state-preview.md | | /courses/video-production-plan/video-production-plan-video-10-workflow-automation-hub-and-branch-strategy | /academy/md/courses/video-production-plan/video-production-plan-video-10-workflow-automation-hub-and-branch-strategy.md | | /courses/video-production-plan/video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks | /academy/md/courses/video-production-plan/video-production-plan-video-11-when-to-customize-configuration-vs-apps-vs-webhooks.md | | /courses/video-production-plan/video-production-plan-video-12-maintainability-governance-and-long-term-ownership | /academy/md/courses/video-production-plan/video-production-plan-video-12-maintainability-governance-and-long-term-ownership.md | | /courses/video-production-plan/video-production-plan-video-13-contentstack-in-a-composable-dxp | /academy/md/courses/video-production-plan/video-production-plan-video-13-contentstack-in-a-composable-dxp.md | ## Supplement for indexing ### Content summary Video Production Plan on Contentstack Academy. ### Retrieval tags - Contentstack Academy - video-production-plan - Video - Production - Plan - Overview - Start - Here - Headless - Foundations - Structured - Content - Composition - Query ### Indexing notes Chunk at each "### Lesson NN — Title" heading; copy lesson_id and topics from the preceding HTML comment into chunk metadata for RAG filters. Course slug: video-production-plan. Union of lesson topic tokens: Video, Production, Plan, Overview, Start, Here, Headless, Foundations, Structured, Content, Composition, Query, API, Architecture, Fetching, and, Performance, Images, Live, Preview, Visual, Builder, Workflow, Automation, When, Customize, Maintainability, Governance, Contentstack, Composable. Do not embed or retrieve LMS-only quiz items or mastery exam answer keys from this export. ### Asset references _No image or video thumbnail URLs were extracted._ ### External links | Label | URL | | --- | --- | | Contentstack Academy home | `https://www.contentstack.com/academy/` | | Training instance setup | `https://www.contentstack.com/academy/training-instance` | | Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` | | Contentstack documentation | `https://www.contentstack.com/docs/` | | Video 3 — Structured Content and API Contracts | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/03-structured-content-and-api-contracts` | | Video 5 — API Architecture, Authentication, and Query Surface Choice | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/05-api-architecture-authentication-query-surface` | | Video 6 — Fetching and Rendering Content with the SDK | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/06-fetching-and-rendering-content` | | Video 8 — Live Preview Architecture and Preview Routing | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/08-live-preview-architecture-and-routing` | | Video 9 — Visual Builder, Releases, and Future-State Preview | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/09-visual-builder-releases-future-state` | | Video 11 — When To Customize: Configuration vs Apps vs Webhooks | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/11-when-to-customize` | | Video 7 — Performance, Images, Environments, and CLI Migrations | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/07-performance-images-environments-cli` | | Video 10 — Workflow, Automation Hub, and Branch Strategy | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/10-workflow-automation-branch-strategy` | | Video 2 — Headless Foundations and Designing for Editors | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/02-headless-foundations-and-designing-for-editors` | | Video 4 — Composition, Query Performance, and Modeling in Practice | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/04-composition-query-performance-modeling` | | Video 1 — Start Here: Certification Roadmap and First API Call | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/01-start-here-certification-roadmap` | | Video 12 — Maintainability, Governance, and Long-Term Ownership | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/12-maintainability-governance-ownership` | | Video 13 — Contentstack in a Composable DXP | `https://contentstack-developer-certification.eu-contentstackapps.com/video-production-plan/13-contentstack-in-composable-dxp` | | github.com/contentstack | `https://github.com/contentstack` |