Skip to main content

Using the Template Editor

Last updated on
Open a doc issue   |   Edit this page

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

Overall, it simplifies template development by providing everything you need in one place. Whether you're creating your first template or debugging complex configurations, the Template Editor streamlines your workflow from idea to deployment.

Prerequisites​

  • 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 UI option​

Each tool serves a specific purpose in the template development lifecycle, allowing you to focus on one aspect at a time for maximum efficiency.


OptionDescriptionWhen to Use
Create New TemplateProvides 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 DirectoryUpload 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 PlaygroundDesign 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 EditorExplore, 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​

  • 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 may 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​

  1. Select Create New Template in the Template Editor.

  2. Create a folder for the template either locally or your local version of the software-templates repo. Then click Select to populate the minimal template files.

  3. Once populated, you'll be presented with two messages to view and save the template files in the folder. Select View files and then Save Changes.

  4. Paste the following yaml code in the template.yaml file.

    apiVersion: scaffolder.backstage.io/v1beta3
    kind: Template
    metadata:
      name: learning-template
      title: My Learning Template
      description: Understanding how templates work
    spec:
      owner: user:guest
      type: service
      
      # These are the form fields users will fill out
      parameters:
        - title: Basic Information
          required:
            - name
          properties:
            name:
              title: Name
              type: string
              description: Name of the component
              
      # These are the actions the template performs
      steps:
        - id: log
          name: Log Message
          action: debug:log
          input:
            message: 'Hello ${{ parameters.name }}!'
            
      # This defines what the user sees after the template runs
      output:
        text:
          - title: 'Template Execution Complete! 🎉'
            content: |
              Your learning template has successfully executed!

  5. Provide a name and click Review > Create to run a dry test.

  6. Check the Log and Output tabs in the Dry-run results.

  7. Modify the template and test again.