Backstage Template Editor

The Template Editor is a browser-based sandbox for experimenting with templates. It offers a live preview and an interactive environment to prototype ideas, understand how templates work, and test configurations before deploying them to your software-templates repository.

The Template Editor is designed for:

• Rapid prototyping — Quickly test template ideas.
• Learning — Understand how templates work through hands-on experimentation.
• Testing — Validate parameter forms, custom fields, and template logic.
• Debugging — Troubleshoot issues in a controlled environment.

Prerequisites

• Knowledge of formatting YAML files.

• Knowledge of Git and creating pull requests.

• You must be a member of the G_GITHUB_PRD_ACCESS global group to contribute templates. To become a member, follow the instructions in the OKTA Workforce Knowledge Base article.

• Review the anatomy of a template. Understanding the structure will help you organize your template logically and ensure it properly collects inputs and executes actions.

• You must have the software-templates repo cloned on your computer. To clone it, see Clone the Templates repo for details.

• Understand the structure of the software-templates repo. For information, see Template Repo Structure

Choose the best user interface (UI) option

Each tool serves a specific purpose in the template development lifecycle. Use the decision chart and table below to select the right tool for your task.

Option	Description	When to use
Create New Template	Provides a minimal blank template to start from scratch. Perfect for: Learning template syntax and structure Prototyping new template ideas Quick experiments without local setup Understanding how template steps work	Building a new template and want a quick starting point.
Load Template Directory	Upload and edit an existing template file directly within the portal. Perfect for: Testing templates before committing to the repository Debugging template issues Making quick adjustments during development Learning from existing template examples	Modifying existing templates or testing complete workflows.
Template Form Playground	Design and test parameter forms in isolation. Perfect for: Rapidly iterating on form design Testing complex parameter configurations Understanding field validations and dependencies Experimenting with multi-step forms	Perfecting form UX without worrying about template logic.
Custom Field Editor	Explore, test, and understand custom form fields before using them in your templates. Perfect for: Discovering what custom fields are available Understanding how custom fields behave Testing field configurations before use Learning field-specific options	Default form fields don't meet your needs.

Debugging issues

Symptom	Tool
Form problems	Template Form Playground
Action failures	Load Template Directly
Field behavior	Custom Field Editor

Common gotchas

1. YAML indentation — Be precise with spacing.
2. Parameter references — Use ${{ parameters.fieldName }}.
3. Step IDs — Must be unique within a template.
4. Custom fields — Not all custom fields might be available in your instance.
5. Saving behavior — Create New Template saves to browser storage; Load Template Directory saves to original files.

---

Simple tutorials to try