Skip to content

Journey Builder Config Tutorial

Last Updated: January 2025
Target Audience: CMS Content Editors
Content Type: Journey Builder Config

Table of Contents

  1. Overview
  2. Accessing the Content Type
  3. Configuring Basic Page Content
  4. Setting Up Form Steps (Advanced)
  5. Configuring Help Text (Advanced)
  6. SEO and Metadata
  7. Multi-Language Support
  8. Best Practices
  9. Troubleshooting
  10. Quick Reference

Overview

This tutorial explains how to manage the Start Journey page content through Strapi CMS. This page allows visitors to design their perfect Portuguese adventure using either an AI assistant chat or a guided form.

What You Can Manage

Page Content: - Page title (main heading) - Page description (introductory text) - Form steps configuration (advanced - for multi-step form structure) - Help text for form fields (advanced - tooltips and guidance) - SEO metadata (for search engines)

Where This Content Appears

The Journey Builder Config controls content on the Start Journey page (/start-journey), which includes: - Hero section with title and description - Mode selector (AI Assistant vs Guided Form) - Form fields and their help text (if configured) - Page metadata for SEO

Note: This is a "Single Type" because there's only one Journey Builder configuration for the entire site (per language).

Accessing the Content Type

  1. Log in to your Strapi CMS admin panel
  2. Navigate to Content Manager in the left sidebar
  3. Click on Single Types (not Collection Types)
  4. Look for Journey Builder Config in the list
  5. Click to open or create a new entry

Note: If you don't see "Journey Builder Config" in the list, contact your development team - the content type may need to be created first.

Configuring Basic Page Content

Step 1: Open Journey Builder Config

  1. Go to Content Manager → Single Types → Journey Builder Config
  2. If this is your first time, you'll see an empty form
  3. Click "Create new entry" or edit the existing entry

Step 2: Set Page Title

The page title is the main heading that appears at the top of the Start Journey page.

  1. In the Page Title field, enter your title
  2. Default: "Design Your Perfect Portuguese Adventure"
  3. Best practices:
  4. Keep it concise (under 60 characters)
  5. Make it engaging and action-oriented
  6. Use a newline (\n) to split into two lines if desired

Page Title Examples

Single Line Two-Line Format
Design Your Perfect Portuguese Adventure Design Your Perfect\nPortuguese Adventure
Create Your Dream Trip to Portugal Create Your Dream Trip\nto Portugal
Plan Your Portuguese Journey Plan Your\nPortuguese Journey

Tip: When using a two-line format, the second line will appear with a gradient color effect. Use \n (backslash + n) to create a line break.

Step 3: Set Page Description

The page description appears below the title and explains what visitors can do on this page.

  1. In the Page Description field, enter your description
  2. Default: "Tell us your dreams, and we'll craft your ideal experience using AI-powered personalization"
  3. Supports rich text formatting:
  4. Bold text: **text** or use the formatting toolbar
  5. Italic text: *text* or use the formatting toolbar
  6. Links: Use the link button in the toolbar
  7. Line breaks: Press Enter

Page Description Examples

Simple Text: 

Tell us your dreams, and we'll craft your ideal experience using AI-powered personalization.

Rich Text with Formatting: 

Tell us your **dreams**, and we'll craft your ideal experience using *AI-powered* personalization.

[Start your journey →](/start-journey)

Multi-Paragraph: 

Discover the perfect Portuguese adventure tailored just for you.

Choose between our **AI Assistant** for a conversational experience or our **Guided Form** for step-by-step planning.

Step 4: Save and Publish

  1. Click "Save" to save your changes (draft)
  2. Click "Publish" to make the changes live on the website
  3. Visit /start-journey on your website to verify changes

Important: Always click "Publish" after making changes. Saving as draft won't make changes visible on the website.

Setting Up Form Steps (Advanced)

Note: This section is for advanced users. Form steps configuration is optional and requires JSON knowledge. If you're not comfortable with JSON, you can skip this section - the form will work with default settings.

The Form Steps field allows you to configure the structure of the multi-step form that appears when users select "Guided Form" mode.

Understanding Form Steps

Form steps define: - How many steps the form has - What fields appear in each step - The order of steps - Step titles

Step 1: Access Form Steps Field

  1. Scroll down to the Form Steps field in the Journey Builder Config
  2. You'll see a JSON editor (code editor)
  3. This field accepts JSON format

Step 2: Basic Form Steps Structure

Here's the basic structure for form steps:

{
  "steps": [
    {
      "id": "step1",
      "title": "Personal Preferences",
      "fields": ["budget", "travelStyle", "groupSize"],
      "order": 1
    },
    {
      "id": "step2",
      "title": "Destination Preferences",
      "fields": ["regions", "interests", "duration"],
      "order": 2
    },
    {
      "id": "step3",
      "title": "Review & Confirm",
      "fields": ["review", "confirm"],
      "order": 3
    }
  ]
}

Step 3: Form Steps Field Reference

Field Type Required Description
id String Yes Unique identifier for the step (e.g., "step1", "step2")
title String Yes Display title for the step (shown to users)
fields Array Yes List of field IDs that appear in this step
order Number Yes Step order (1, 2, 3...)

Step 4: Common Field IDs

Here are some common field IDs you might use:

Field ID Description
budget Budget range selection
travelStyle Travel style preferences
groupSize Number of travelers
regions Preferred regions/destinations
interests Interest categories
duration Trip duration
dates Travel dates
accommodation Accommodation preferences
activities Activity preferences
review Review summary
confirm Confirmation checkbox

Note: Field IDs must match the actual form field IDs used in the frontend. Contact your development team if you need to add new fields.

Step 5: Example Form Steps Configuration

Example 1: Simple 3-Step Form 

{
  "steps": [
    {
      "id": "step1",
      "title": "Tell Us About Yourself",
      "fields": ["groupSize", "travelStyle"],
      "order": 1
    },
    {
      "id": "step2",
      "title": "Choose Your Preferences",
      "fields": ["regions", "interests", "duration"],
      "order": 2
    },
    {
      "id": "step3",
      "title": "Review Your Journey",
      "fields": ["review", "confirm"],
      "order": 3
    }
  ]
}

Example 2: Detailed 5-Step Form 

{
  "steps": [
    {
      "id": "step1",
      "title": "Basic Information",
      "fields": ["groupSize", "travelStyle", "budget"],
      "order": 1
    },
    {
      "id": "step2",
      "title": "Destination & Dates",
      "fields": ["regions", "dates", "duration"],
      "order": 2
    },
    {
      "id": "step3",
      "title": "Interests & Activities",
      "fields": ["interests", "activities"],
      "order": 3
    },
    {
      "id": "step4",
      "title": "Accommodation",
      "fields": ["accommodation"],
      "order": 4
    },
    {
      "id": "step5",
      "title": "Review & Submit",
      "fields": ["review", "confirm"],
      "order": 5
    }
  ]
}

Step 6: Validating JSON

Before saving, make sure your JSON is valid:

  1. Check for syntax errors:
  2. All strings must be in double quotes (")
  3. Commas between items (but not after the last item)

  4. Matching brackets {} and []

  5. Use a JSON validator:

  6. Copy your JSON
  7. Paste into jsonlint.com

  8. Fix any errors before saving

  9. Common errors:

  10. Missing comma: {"id": "step1" "title": "..."} ❌
  11. Correct: {"id": "step1", "title": "..."} ✅
  12. Trailing comma: {"id": "step1",} ❌
  13. Correct: {"id": "step1"} ✅

Warning: Invalid JSON will cause errors. Always validate before saving!

Configuring Help Text (Advanced)

Note: This section is for advanced users. Help text configuration is optional and requires JSON knowledge.

The Help Text field allows you to provide tooltips and guidance text for form fields.

Understanding Help Text

Help text appears: - As tooltips when users hover over fields - As placeholder text in form inputs - As helper text below fields

Step 1: Access Help Text Field

  1. Scroll down to the Help Text field in the Journey Builder Config
  2. You'll see a JSON editor
  3. This field accepts JSON format (key-value pairs)

Step 2: Basic Help Text Structure

Here's the basic structure:

{
  "budget": "Enter your budget range for the entire trip in euros",
  "travelStyle": "Select your preferred travel style (relaxed, adventurous, cultural, etc.)",
  "groupSize": "Number of travelers including yourself",
  "regions": "Select one or more regions you'd like to visit",
  "interests": "Choose activities that interest you (food, history, nature, etc.)",
  "duration": "How many days do you want to spend in Portugal?"
}

Step 3: Help Text Format

  • Key: Field ID (must match form field IDs)
  • Value: Help text string (plain text or HTML)

Step 4: Example Help Text Configuration

Simple Text: 

{
  "budget": "Enter your total budget for the trip",
  "groupSize": "Include yourself in the count",
  "dates": "Select your preferred travel dates"
}

Detailed Text: 

{
  "budget": "Enter your total budget for the entire trip in euros. This includes accommodation, activities, and meals. Typical budgets range from €500-€5000 per person.",
  "travelStyle": "Select your preferred travel style:\n• Relaxed: Leisurely pace, lots of downtime\n• Adventurous: Active experiences, outdoor activities\n• Cultural: Museums, historical sites, local culture\n• Food-focused: Culinary experiences, wine tours",
  "groupSize": "Number of travelers including yourself. This helps us recommend appropriate accommodations and activities.",
  "regions": "Select one or more regions you'd like to visit. You can choose multiple regions for a multi-city trip.",
  "interests": "Choose activities that interest you. You can select multiple options. This helps us personalize your experience recommendations.",
  "duration": "How many days do you want to spend in Portugal? Consider travel time to and from Portugal when planning."
}

Step 5: Using HTML in Help Text

You can use basic HTML formatting:

{
  "budget": "Enter your budget. <strong>Tip:</strong> Budgets typically range from €500-€5000 per person.",
  "travelStyle": "Select your style. <a href='/about' target='_blank'>Learn more about our travel styles</a>."
}

Note: HTML support may vary. Keep it simple (bold, italic, links) for best compatibility.

Step 6: Validating Help Text JSON

Follow the same validation steps as Form Steps: 1. Use double quotes for keys and values 2. Separate items with commas 3. Validate using jsonlint.com

SEO and Metadata

SEO fields help your page rank better in search engines and display nicely when shared on social media.

Step 1: Meta Title

  1. Scroll to Meta Title field
  2. Enter a title optimized for search engines
  3. Best practices:
  4. 50-60 characters (including spaces)
  5. Include keywords: "Portugal", "travel", "adventure"
  6. Make it compelling and descriptive

Examples: - Design Your Perfect Portuguese Adventure | Portugal Odyssey - Plan Your Dream Trip to Portugal - Custom Experience Builder - Create Personalized Portugal Travel Experiences

Step 2: Meta Description

  1. Scroll to Meta Description field
  2. Enter a description that appears in search results
  3. Best practices:
  4. 150-160 characters
  5. Include a call-to-action
  6. Mention key benefits

Examples: - Design your perfect Portuguese adventure with our AI-powered journey builder. Tell us your dreams and we'll create a personalized experience just for you. - Plan your dream trip to Portugal. Use our interactive form or AI assistant to create a customized travel experience tailored to your preferences.

Step 3: Meta Keywords

  1. Scroll to Meta Keywords field
  2. Enter relevant keywords separated by commas
  3. Best practices:
  4. 5-10 keywords
  5. Include location, activity types, and service keywords

Examples: - Portugal travel, Portuguese adventure, custom travel, travel planning, Portugal experiences - Portugal, travel planning, personalized trips, Portuguese culture, adventure travel

Step 4: Open Graph Image

  1. Scroll to OG Image field
  2. Click "Click to add an asset" or "Drop files here"
  3. Upload an image that represents your page
  4. Best practices:
  5. Size: 1200x630px (recommended)
  6. Format: JPG or PNG
  7. Include text overlay with page title
  8. High quality, visually appealing

Note: This image appears when your page is shared on social media (Facebook, Twitter, LinkedIn, etc.)

Step 5: Canonical URL

  1. Scroll to Canonical URL field
  2. Enter the canonical URL for this page
  3. Format: Full URL including domain
  4. Example: https://www.portugalodyssey.pt/start-journey

Note: Usually only needed if you have duplicate content or multiple URLs pointing to the same page.

Multi-Language Support

Journey Builder Config supports multiple languages, allowing you to provide localized content for different audiences.

Available Languages

  • English (en) - Default
  • Portuguese (pt)
  • Spanish (es)
  • French (fr)

Switching Languages

  1. In the content editor, look for the language selector (usually in the top right)
  2. Click to see available languages
  3. Select a language to edit content for that locale
  4. Each language has its own content - you must configure each separately

Language-Specific Fields

The following fields support multi-language: - Page Title - Translated for each language - Page Description - Translated for each language - Meta Title - Translated for each language - Meta Description - Translated for each language - Meta Keywords - Translated for each language

Fields that are NOT translated: - Form Steps - Same structure for all languages (field IDs are universal) - Help Text - Can be translated, but field IDs remain the same - OG Image - Usually the same image for all languages - Canonical URL - Usually the same URL

Best Practice for Multi-Language

  1. Start with your primary language (usually English or Portuguese)
  2. Complete all fields for the primary language
  3. Switch to other languages and translate content
  4. Maintain consistency:
  5. Keep the same tone and style
  6. Use similar length for titles and descriptions
  7. Ensure cultural appropriateness
  8. Test each language on the website to verify display

Translation Examples

English (en): - Page Title: Design Your Perfect Portuguese Adventure - Page Description: Tell us your dreams, and we'll craft your ideal experience using AI-powered personalization.

Portuguese (pt): - Page Title: Desenhe a Sua Aventura Portuguesa Perfeita - Page Description: Conte-nos os seus sonhos e criaremos a experiência ideal usando personalização com IA.

Spanish (es): - Page Title: Diseña Tu Aventura Portuguesa Perfecta - Page Description: Cuéntanos tus sueños y crearemos tu experiencia ideal usando personalización con IA.

French (fr): - Page Title: Concevez Votre Aventure Portugaise Parfaite - Page Description: Dites-nous vos rêves et nous créerons votre expérience idéale en utilisant la personnalisation IA.

Best Practices

Page Title

  1. Keep it concise: Under 60 characters for best display
  2. Make it engaging: Use action words (Design, Create, Plan)
  3. Include key terms: Mention "Portugal" and "Adventure"
  4. Test readability: Read it aloud to ensure it flows well
  5. Consider two-line format: Split long titles for visual impact

Page Description

  1. Be clear and concise: Explain what users can do
  2. Include benefits: Mention AI-powered, personalized, etc.
  3. Use formatting: Bold important words, add line breaks
  4. Keep it scannable: Use short paragraphs or bullet points
  5. Include call-to-action: Encourage users to start

Form Steps (Advanced)

  1. Start simple: Begin with 3-4 steps, add more if needed
  2. Logical flow: Group related fields together
  3. Clear step titles: Make it obvious what each step covers
  4. Test thoroughly: Verify all field IDs exist
  5. Document changes: Keep notes of field IDs you're using

Help Text (Advanced)

  1. Be helpful: Provide clear, actionable guidance
  2. Keep it short: One or two sentences per field
  3. Use examples: Show users what to enter
  4. Be consistent: Use similar tone and style
  5. Update regularly: Keep help text current with form changes

SEO

  1. Unique content: Don't duplicate content from other pages
  2. Keyword research: Use terms your audience searches for
  3. Optimize images: Use descriptive filenames and alt text
  4. Test sharing: Share your page on social media to preview OG image
  5. Monitor performance: Check search rankings and adjust as needed

General

  1. Save drafts frequently: Use "Save" before "Publish"
  2. Preview before publishing: Check content in CMS preview if available
  3. Test on website: After publishing, verify changes appear correctly
  4. Document changes: Keep notes of what was changed and when
  5. Backup content: Copy important text before making major changes

Troubleshooting

Page title not updating

Problem: Changes to page title don't appear on the website.

Solutions: 1. Check that content is Published (not just saved as draft) 2. Clear browser cache - try hard refresh (Ctrl+F5 or Cmd+Shift+R) 3. Verify the correct language is selected on the website 4. Check that you're editing the correct language in CMS 5. Wait a few minutes - changes may take time to propagate

Page description formatting not working

Problem: Rich text formatting (bold, links) doesn't appear correctly.

Solutions: 1. Verify you're using the rich text editor (not plain text) 2. Check that HTML tags are properly formatted 3. Ensure you're using supported formatting (bold, italic, links) 4. Test formatting in the CMS preview if available 5. Contact development team if complex formatting is needed

Form steps not working

Problem: Form steps configuration doesn't affect the form.

Solutions: 1. Validate JSON: Check for syntax errors using jsonlint.com 2. Verify field IDs: Ensure field IDs match actual form fields 3. Check structure: Verify JSON follows the correct format 4. Contact development: Form steps require matching frontend implementation 5. Test incrementally: Add one step at a time to identify issues

Help text not appearing

Problem: Help text doesn't show for form fields.

Solutions: 1. Validate JSON: Check for syntax errors 2. Verify field IDs: Ensure field IDs match form field IDs exactly 3. Check format: Verify JSON structure is correct (key-value pairs) 4. Test field IDs: Contact development team to confirm field IDs 5. Clear cache: Clear browser cache and refresh

SEO metadata not showing in search results

Problem: Meta title/description don't appear in Google search results.

Solutions: 1. Wait for indexing: Google may take days/weeks to re-index 2. Check length: Ensure meta title is 50-60 chars, description 150-160 chars 3. Verify publishing: Ensure content is published (not draft) 4. Use Google Search Console: Submit URL for re-indexing 5. Check robots.txt: Ensure page isn't blocked from indexing

Multi-language content not showing

Problem: Content appears in wrong language or default language.

Solutions: 1. Verify you're editing the correct language in CMS 2. Check that content is published for that language 3. Ensure website language selector is set correctly 4. Clear browser cache and cookies 5. Check that i18n plugin is enabled in Strapi

JSON validation errors

Problem: Form Steps or Help Text fields show validation errors.

Solutions: 1. Check syntax: Ensure all strings use double quotes (") 2. Remove trailing commas: No comma after last item in arrays/objects 3. Match brackets: Ensure all { have matching } and [ have matching ] 4. Use validator: Copy JSON to jsonlint.com to find errors 5. Start fresh: If stuck, delete content and start with a simple example

Quick Reference

Journey Builder Config Fields

Field Type Required Description
Page Title Text Yes Main page heading
Page Description Rich Text Yes Introductory text below title
Form Steps JSON No Multi-step form configuration (advanced)
Help Text JSON No Field help text and tooltips (advanced)
Meta Title Text No SEO title (50-60 chars)
Meta Description Text No SEO description (150-160 chars)
Meta Keywords Text No SEO keywords (comma-separated)
OG Image Media (Image) No Social media preview image (1200x630px)
Canonical URL Text No Canonical URL for SEO

Form Steps JSON Structure

{
  "steps": [
    {
      "id": "step1",
      "title": "Step Title",
      "fields": ["field1", "field2"],
      "order": 1
    }
  ]
}

Help Text JSON Structure

{
  "fieldId": "Help text for this field",
  "anotherField": "Help text for another field"
}

Common Field IDs Reference

Field ID Typical Use
budget Budget range selection
travelStyle Travel style preferences
groupSize Number of travelers
regions Preferred destinations
interests Interest categories
duration Trip duration
dates Travel dates
accommodation Accommodation type
activities Activity preferences

Page Title Examples

Format Example
Single Line Design Your Perfect Portuguese Adventure
Two-Line Design Your Perfect\nPortuguese Adventure
Action-Oriented Create Your Dream Trip to Portugal
Question Format Ready to Plan Your Portuguese Adventure?

Page Description Examples

Style Example
Simple Tell us your dreams, and we'll craft your ideal experience.
With Formatting Tell us your **dreams**, and we'll create your ideal experience.
Multi-Paragraph Discover the perfect Portuguese adventure.\n\nChoose between our AI Assistant or Guided Form.
With Link Start planning your trip. [Learn more →](/about)

SEO Best Practices

Field Optimal Length Tips
Meta Title 50-60 chars Include keywords, be compelling
Meta Description 150-160 chars Include call-to-action, mention benefits
Meta Keywords 5-10 keywords Use location, activity, service terms
OG Image 1200x630px Include text overlay, high quality

Additional Resources

  • Strapi Documentation: https://docs.strapi.io
  • Content Manager Guide: See Strapi admin panel help section
  • Media Library: Use Strapi Media Library to manage images
  • i18n Plugin: See Strapi i18n documentation for multi-language setup
  • JSON Validator: https://jsonlint.com

Support

If you encounter issues not covered in this tutorial:

  1. Check the Troubleshooting section
  2. Review Strapi documentation
  3. Contact your development team (especially for Form Steps and Help Text)
  4. Check website error logs (if accessible)
  5. Test with simple examples first before complex configurations
  • Navigation and Footer Configuration - Learn how to manage site navigation and footer
  • Contact Page Tutorial (coming soon) - Learn how to manage contact page content
  • About Page Tutorial (coming soon) - Learn how to manage about page content

End of Tutorial