CaaS/OCM Developer
Quickstart Guide

Introduction

What is CaaS (Content-as-a-Service)?

CaaS is FirstSpirit's headless content delivery service that exposes your content through a RESTful JSON API.

Key capabilities include:

• Retrieve content from FirstSpirit without server-side rendering
• Build modern single-page applications, mobile apps, and digital experiences
• Consume content across multiple channels and platforms
• Maintain content once and deliver it everywhere

What is OCM (Omnichannel Manager)?

The Omnichannel Manager is FirstSpirit's interface for managing headless content delivery, providing:

• Visual content editing for headless applications
• Content orchestration across multiple channels
• Preview capabilities for headless frontends
• Dataset management for structured content

Benefits of the Headless CMS Approach

Flexibility

Build your frontend with any technology stack (React, Vue, Angular, native mobile, etc.)

Performance

Deliver static JSON content that can be cached and served at scale.

Future-proof

Decouple content from presentation, making it easier to adapt to new channels.

Developer Experience

Use modern frameworks and tools you're already familiar with.

When to Use CaaS/OCM

CaaS is ideal for:

• Modern web applications (SPAs, PWAs)
• Mobile applications (iOS, Android)
• Multi-channel content delivery (web, mobile, kiosks, IoT)
• Microservices architectures
• Jamstack applications

Consider traditional FirstSpirit rendering if you need:

• Server-side rendering with FirstSpirit templates
• Legacy system integration
• Complex server-side business logic

Prerequisites

Development Environment

• Node.js: Version 16.x or higher
• Package Manager: npm or pnpm
• Text Editor: VS Code recommended (with Prettier extension)
• Modern Browser: Chrome, Firefox, or Edge (with developer tools)

FirstSpirit Credentials

Browser Requirements

The guide uses modern JavaScript features:

• Fetch API
• ES6+ syntax (arrow functions, template literals, destructuring)
• Async/await

Supported browsers: Chrome 60+, Firefox 60+, Safari 12+, Edge 79+.

Core Concepts

CaaS Architecture

CaaS provides a REST API that serves FirstSpirit content as JSON through this flow:

[FirstSpirit CMS] → [CaaS API] → [Your Application] → [End User]

Content is automatically synchronized from FirstSpirit to the CaaS backend, where it's indexed and made available via REST endpoints.

Content Modes

CaaS operates in two modes:

Preview Mode (preview)

• Shows unpublished content changes
• Used when editing in FirstSpirit ContentCreator
• Includes draft and in-progress content
• Requires authentication

Release Mode (release)

• Shows only published, production-ready content
• Used for live websites and applications
• Optimized for performance
• Can be publicly accessible

URL pattern:

${CAAS_URL}/${TENANT_ID}/${PROJECT_ID}.${caasMode}.content

Navigation Service

The Navigation Service provides a hierarchical tree of your site structure:

• Menu items and their hierarchy
• SEO-friendly routes (slugs)
• Content references (links to CaaS content)
• Metadata (labels, page types, custom attributes)

URL pattern:

https://${TENANT_ID}-navigationservice.e-spirit.cloud/navigation/${caasMode}.${PROJECT_ID}?language=${locale}

TPP_SNAP Library

TPP_SNAP (Third-Party Preview SNAP) is FirstSpirit's JavaScript library for in-context editing. It enables:

• Click-to-edit functionality in preview mode
• Communication between your app and ContentCreator
• Content creation directly from your frontend
• Custom toolbar buttons and interactions

Load it from your FirstSpirit instance:

<script src="https://YOUR-FIRSTSPIRIT-HOST/fs5webedit/live/live.js"></script>

Template Types and UID Conventions

FirstSpirit uses template UIDs to identify different content types:

Getting Started

Let's build your first CaaS application. We'll start with a minimal setup that connects to CaaS and fetches navigation data.

Project Setup

1. Create a new project directory:

mkdir my-caas-app
cd my-caas-app

2. Create the following file structure:

my-caas-app/
├── index.html
├── settings.js
└── app.js

Configuration File (settings.js)

Create settings.js with your CaaS credentials:

// CaaS Configuration
// Replace these values with your actual credentials
const CAAS_URL = 'https://YOUR-TENANT-caas-api.e-spirit.cloud';
const TENANT_ID = 'your-tenant';
const PROJECT_ID = 'your-project-uuid';
const CAAS_API_KEY = 'your-api-key';

// Locale configuration
var LOCALE = {
    identifier: "EN",
    country: "US",
    language: "en"
};
LOCALE.locale = `${LOCALE.language}_${LOCALE.country}`;

// Request header with authentication
const REQUEST_HEADER = {
    method: 'GET',
    headers: {
        Authorization: `Bearer ${CAAS_API_KEY}`,
    },
};

Application Script (app.js)

Create app.js:

// Helper function to fetch JSON from CaaS
const getJsonContentByURL = (url, callback) => {
    fetch(url, REQUEST_HEADER)
        .then((res) => {
            if (!res.ok) {
                throw new Error(`HTTP ${res.status}: ${res.statusText}`);
            }
            return res.json();
        })
        .then((json) => callback(json))
        .catch((error) => {
            console.error('CaaS fetch error:', error);
        });
};

For a complete working example, see examples/01-basic-setup/ in this repository.

Working with the Navigation Service

The Navigation Service is typically the entry point for CaaS applications. It provides your site's structure and routes to content.

Key Concepts

• seoRoute: The URL path for each page
• label: Display text for navigation
• contentReference: Full CaaS URL to fetch page content
• children: Nested navigation items for submenus

For complete navigation examples, see examples/02-navigation/.

Rendering Page Content

Pages are fetched using their contentReference URL from the navigation. Content is stored in the formData object, keyed by template field UIDs.

Key Patterns

• Access page fields via pageRef.page.formData.pt_fieldname.value
• Media references contain a URL pointing to resolution metadata
• Use the setImageSource() helper to resolve image resolutions
• Rich text fields contain HTML that can be used with innerHTML

For complete page rendering examples, see examples/03-page-content/.

Section Templates

Sections are the building blocks of page content. Each section has an fsType and template.uid that determines how to render it.

Common Section Types

• text_picture: Text with an image
• slider: Carousel with multiple slides (uses st_catalog)

For complete section examples, see examples/04-sections/.

Content2Section (Datasets)

Content2Section is used for structured data managed in the FirstSpirit dataset module. Unlike regular sections, you query datasets separately using MongoDB-style filters.

Query Operators

• $and: All conditions must match
• $in: Value is in array
• $gte, $lte: Comparison operators
• $regex: Pattern matching

For complete dataset examples, see examples/05-datasets/.

Preview Mode & TPP_SNAP Integration

TPP_SNAP enables in-context editing when your application is loaded in FirstSpirit ContentCreator.

Key Methods

• TPP_SNAP.onInit(callback): Detect ContentCreator connection
• TPP_SNAP.setPreviewElement(identifier): Set current preview element
• TPP_SNAP.onRequestPreviewElement(callback): Handle page navigation
• TPP_SNAP.onRerenderView(callback): Handle content updates
• TPP_SNAP.createSection(pageId, options): Create new sections
• TPP_SNAP.createDataset(schemaId, options): Create new datasets
• TPP_SNAP.registerButton(config, position): Add custom toolbar buttons

For complete preview mode examples, see examples/06-preview-mode/.

Best Practices

Error Handling

Always handle errors gracefully with user-friendly messages and proper logging.

Loading States

Show loading indicators for better UX while content is being fetched.

Content Caching

Implement client-side caching to reduce API calls (clear cache in preview mode).

Null Safety

Always use optional chaining (?.) when accessing nested properties.

Security

Never expose API keys in client code. Use server-side proxies in production.

Performance

Lazy load images, debounce filter changes, and minimize API calls.

Troubleshooting

Common Errors

CORS Errors

Verify your API key permissions and ensure you're using a web server (not file:// protocol). Contact your FirstSpirit administrator to add your domain to allowed origins.

401 Unauthorized

Check that CAAS_API_KEY is correct and hasn't expired. Verify the Authorization header format: Bearer YOUR_KEY.

404 Not Found

Verify PROJECT_ID (should be a UUID), check TENANT_ID, and ensure you're using the correct caasMode.

TPP_SNAP is Undefined

Ensure live.js is loaded before your app script. Always check if TPP_SNAP exists before using it.

Resources & Next Steps

Official Documentation

• Crownpeak FirstSpirit OCM Documentation
• Navigation Service Documentation
• JavaScript Content API Library
• Crownpeak PWA Template

Example Code

This guide includes complete working examples:

1. examples/01-basic-setup/: Minimal CaaS connection
2. examples/02-navigation/: Navigation Service integration
3. examples/03-page-content/: Page rendering with formData
4. examples/04-sections/: Section template handling
5. examples/05-datasets/: Content2Section with filters
6. examples/06-preview-mode/: Full TPP_SNAP integration