Plan your app

Plan your app's scope, type, and versioning strategy before you start building.

Prerequisites

Ensure you have the following:

• OCP CLI – Install the OCP command-line interface and log in.
• Node.js – Install Node.js 22 or later. OCP apps require Node.js 22 or later. Install Node.js 22 or later. OCP apps require Node.js 22 or later. See [supported Node.js versions] for details.
• OCP account access – Have developer access to an OCP account. Contact Optimizely Support if you do not have developer access.

Key concepts

The following terms are used throughout this guide:

• App – A custom-built application deployed to OCP, consisting of a manifest (app.yml), source code, schema definitions, and form definitions.
• App version – A specific release of an app, identified by APP_ID@VERSION, such as [email protected]. Versions follow semantic versioning, a three-part numbering system (major, minor, patch) that indicates the scope of a change, with optional pre-release tags.
• Installation – An instance of an app running in a specific OCP account. Each installation has its own settings, storage, and lifecycle state.

App structure

An OCP app consists of a manifest (app.yml), source code, schema definitions, and form definitions. The app manifest defines the functionalities provided by your app. See App structure for a breakdown of the project layout.

Runtime environment

OCP apps run on a managed, serverless Node.js platform. Apps are written in TypeScript and run on Node.js 22. See Configure your development environment for setup instructions.

Choose your app type

OCP supports several app types. Choose the type that fits your use case.

Data sync source

A data sync source provides data from an external system to OCP through the Sync Manager. Use this type to import data from an external system into OCP. Users can then access this data in Optimizely products, such as Optimizely CMS.

See Data sync source for implementation details.

Data sync destination

Receives data from OCP and sends it to an external system through the Sync Manager. Use this type to export Optimizely data to an external platform, for example, Content Management System (CMS) content from Graph or assets from Optimizely Content Marketing Platform (CMP).

See Data sync destination for implementation details.

Opal tool

Extends the Opal AI assistant with custom tool capabilities. Use this type when you want the Opal assistant to retrieve data or perform actions in external systems on behalf of the user.

See the Opal tool reference app end-to-end guide for a complete walkthrough.

Generic

Supports functions, jobs, a settings form, and lifecycle hooks. Use this type for integrations that do not fit one of the specialized types above. Generic apps can use OCP capabilities, such as storage, and communicate with Optimizely and external services through APIs.

Plan your version strategy

OCP uses semantic versioning (MAJOR.MINOR.PATCH) with pre-release tags:

Development

Use -dev tags, such as 1.0.0-dev.1, during development and testing. Dev versions are limited to your associated OCP accounts, cannot be shared with other accounts, and bypass the app review process. Increment the dev tag as you iterate, like 1.0.0-dev.2, 1.0.0-dev.3.

Pre-release testing

📘

Beta

The following feature is in beta.

Use -beta tags, like 1.0.0-beta to share pre-release versions with selected testers. Beta versions can only be installed with the OCP CLI. Beta versions require review approval.

Production release types

When your app is ready for production, choose one of the following release types:

• Normal version – Remove the pre-release tag, like 1.0.0. The app is publicly available to all Optimizely customers in the App Directory.
• Private version – Use the -private tag, like 1.0.0-private. The app is released to production, but availability is limited to selected OCP accounts. Use this when you want to release production-ready functionality but control who can install the app.

Both release types require review approval by Optimizely.

Auto-upgrade behavior

OCP handles version upgrades differently depending on whether the update is a major or non-major release.

OCP auto-upgrades existing installations when you publish a non-major version update, like MINOR or PATCH. For example, publishing version 1.1.0 automatically upgrades all installations running 1.0.x. Major version updates such as 1.0.0 to 2.0.0 require the end-user to click Upgrade in the App Directory.

Pre-release versions also auto-upgrade within the same tag. For example, publishing 1.0.0-dev.2 automatically upgrades installations running 1.0.0-dev.1.

See App versioning for details on how OCP handles version upgrades.