---
title: "CaaS/OCM Developer Quickstart Guide"
source: caas-ocm-quickstart.html
---

# CaaS/OCM Developer Quickstart Guide

> A comprehensive guide for developers getting started with Crownpeak FirstSpirit's CaaS (Content-as-a-Service) and OCM (Omnichannel Manager) — from prerequisites and core concepts to rendering content, datasets, and in-context preview editing.

## Introduction

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

> [!NOTE]
> 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

| Credential | Description | Example |
| --- | --- | --- |
| `CAAS_URL` | Your CaaS API endpoint | `https://your-tenant-caas-api.e-spirit.cloud` |
| `TENANT_ID` | Your tenant identifier | `your-tenant` |
| `PROJECT_ID` | The UUID of your FirstSpirit project | `12345678-90ab-cdef-1234-567890abcdef` |
| `CAAS_API_KEY` | Bearer token for API authentication | `your-api-key-here` |
| Navigation Service URL | The endpoint for navigation data | `https://${TENANT_ID}-navigationservice.e-spirit.cloud` |

### 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:

```html
<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:

| Type | Prefix | Description | Examples |
| --- | --- | --- | --- |
| Page Templates | `pt_*` | Define the overall structure of a page | `pt_headline`, `pt_headerpicture` |
| Section Templates | `st_*` | Define reusable content blocks within a page | `st_text`, `st_picture`, `st_catalog` |
| Dataset Templates | `tt_*` | Define structured data entities (Content2Section) | `tt_name`, `tt_price`, `tt_category` |

## 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:

```bash
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:

```javascript
// 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}`,
    },
};
```

> [!WARNING]
> Never commit real API keys to version control. Add `settings.js` to your `.gitignore` or use environment variables in production.

### Application Script (app.js)

Create `app.js`:

```javascript
// 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](https://docs.crownpeak.com/firstspirit/ocm/)
- [Navigation Service Documentation](https://navigationservice.e-spirit.cloud/docs/user/en/documentation.html)
- [JavaScript Content API Library](https://github.com/e-Spirit/javascript-content-api-library)
- [Crownpeak PWA Template](https://github.com/e-Spirit/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