Beginner's Guide for Optimizely Backend Developers

Developing with Optimizely (formerly Episerver) requires more than just technical know‑how. It’s about respecting the editor’s perspective, ensuring performance, and applying conventions that make content management sustainable. Below are some of the most common mistakes that beginner Optimisely developers make that I have collected from number of different projects I had a chance to work on in the last couple of years.

Respect Editorial Settings

• Always account for languages, publish status, access rights, and personalization settings.
• Don’t rely solely on ContentRepository to fetch content — editors can apply rules in edit mode that must be respected.
• In multilingual implementations, be sure to return correct language, taking care of fallback settings that editor can set.
• Use Search & Navigation APIs to retrieve lists of pages, applying filters for deleted or unpublished content, and excluding restricted pages like 404s.
• Also be prepared to have a fallback strategy in case Search & Navigation API is not accessible.
• Take care of all LinkItem properties when rendering link on the page like title and target.

Caching Strategies

• Cache global settings and common page elements to improve performance.
• Always tend to cache view models, never Optimizely data models, to avoid unnecessary memory consumption.
• Take care of cache invalidation strategy.

Modeling Content Types

• Think from the editor’s perspective when designing page types and blocks.
• Make sure to provide smooth editing experience.
• Apply SOLID programming principles
• Take care on usage of base classes, interfaces and inheritance.
• When modeling content types and properties always ask following questions:
  • is it going to be reusable?
  • is it going to contain one or more items?
  • is it global or site related?
  • is it required or optional?
  • can it have a default value?
  • is it localizable?
  • is it searchable?
  • what can be validation rules?
• Use ContentArea when you need:
  • Personalization
  • Grouping blocks
  • Applying grid settings
• Use XHtmlString when you need rich text editing capability, but be aware that XHtmlString is also a container for all other content types, similar as ContentArea it supports personalization
• Use blocks when you need reusable content or when you need to apply personalization in ContentArea.
• Use block as property type to group more properties, that also makes those properties easy editable in page preview mode
• Avoid nesting more than two levels of blocks to prevent performance and indexing issues.
• For dynamic content nesting, prefer IList<BlockType> property with BlockType defined as AvailableInEditMode = false.
• Learn and leverage out‑of‑the‑box property selections.
• Remember: any change to a content type model mutates the database, except attribute values like DisplayName or validation rules.
• Property removed from the code is NOT removed from the database, be sure to clean up those properties from Admin mode.
• When you need to validate input from editor, use validation attribute instead of Saving event.
• Determine carefully which content types can be nested within others, and specify which blocks are permitted in the Content Area.
• Avoid creating circular references between content types, as this can lead to infinite loops and cause problems with Find indexing.

Scheduled Jobs

• Scheduled jobs behave differently when run manually versus automatically.
• When manually triggered, that means you are logged in and it will use your user principal.
• Ensure the correct user principal is set when running scheduled job automatically and when accessing protected content.
• Monitor for job stopped signals during execution to handle interruptions gracefully.
• Be sure to disable Scheduled Jobs in the development environment to avoid jobs running in the background without notice.

Site and Domain Awareness

• The current domain in the URL determines the active site.
• Review site settings carefully: a site with * in its host list will respond to all domains pointing to that server.

Rich Text Editing

• Configure TinyMCE options: fonts, styles, plugins, allowed blocks, and personalization features.
• Understand the relationship between XHtmlString and ContentArea:

• • XHtmlString is a flexible container for any content, renders as a TinyMCE editor.
  • ContentArea inherits from XHtmlString and renders just as a content container.

Property Management

• Properties can define type, default values, and attributes such as UIHint, Validation, Localization, Display, and rendering options.
• Control how properties are rendered and their visibility in edit mode.
• Use events carefully, casting to the lowest possible type (e.g., interface) to ensure correctness.

Find Indexing

• Take care on content that needs to be indexed, add necessary indexing conventions.
• Take care when setting up development environment not to use Optimizely DXP indexing service URL, otherwise content from you local DB might end up there.

Conclusion

Optimizely development is not just about writing code — it’s about creating a seamless experience for editors, ensuring performance, and applying conventions that scale. By respecting editorial settings, caching wisely, modeling content thoughtfully, and configuring tools like TinyMCE, developers can deliver solutions that empower both content creators and end users.