Skip to main content

​
What you will achieve

By the end of this tutorial you will have:
  • A working sheet configuration with columns for UserNeed and related SystemRequirement entities
  • A data source that queries and expands the entity hierarchy from your domain model
  • A complete configuration ready to be linked to a Powersheet document
diagram

​
Prerequisites

​
Step 1: Open the sheet configuration administration

Navigate to Administration > Nextedy POWERSHEET > Sheet Configurations. Click New at the project level. Select System Default as the base and give your configuration a name (e.g., rtm-sheet). You should see: A new sheet configuration file opens in the editor with default template content.
Sheet configuration files use YAML syntax. Indentation must use spaces (not tabs), and each nesting level uses two spaces. Most configuration errors come from incorrect indentation. For a complete introduction to YAML syntax, see the YAML Primer.

​
Step 2: Define columns

Replace the editor content with the following YAML. This defines columns for the root UserNeed entity and nested columns for related SystemRequirement entities: 
columns:
  title:
    title: User Need
    width: 250
    hasFocus: true
  severity:
    title: Severity
    width: 120
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 200
  systemRequirements.systemRequirement.severity:
    title: SR Severity
    width: 120
Each key under columns is a binding path that references properties from your domain model. A simple key like title refers to a property on the root entity type. A dot-separated path navigates through relationships defined in the domain model:
Path segmentMeaning
systemRequirementsThe direct navigation property from your domain model relationship
systemRequirementThe target entity type name
titleThe property to display from the target entity
You should see: Four column definitions in the YAML editor.
The title property sets the column header text. Without it, the header defaults to the binding path (e.g., 0.systemRequirements.systemRequirement.title), which is not user-friendly. Always set an explicit title for clarity.

​
Step 3: Define the data source

Add a sources section below the columns. This tells Powersheet which entity type to query and which relationships to expand when loading data: 
sources:
  - id: requirements
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
The source configuration has three key parts:
  • id (required) — a unique identifier you choose for this data source. You can name it anything meaningful
  • query.from (required) — the root entity type name, matching a key in domainModelTypes from your domain model
  • expand (optional) — which relationships to follow when loading data. Each name corresponds to a navigation property from your domain model. Expansion can be nested to follow multi-level relationships
You should see: The complete configuration now has both columns and sources sections.
Built-in properties like id and title do not need to be explicitly defined in your sources or domain model to be queried; they are implicitly available. However, you must explicitly list them in your columns section if you want them to appear in the sheet.
The query.from value must exactly match a domainModelTypes key from your domain model. If you defined UserNeed in the domain model, you must use UserNeed here — not userneed or user_need. The match is case-sensitive.

​
Step 4: Review the complete configuration

Your complete sheet configuration should look like this: 
columns:
  title:
    title: User Need
    width: 250
    hasFocus: true
  severity:
    title: Severity
    width: 120
  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 200
  systemRequirements.systemRequirement.severity:
    title: SR Severity
    width: 120

sources:
  - id: requirements
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
Save the configuration file. You should see: The editor accepts the YAML without errors. The configuration is now stored in your project repository. To see your sheet in action, link this configuration to a Powersheet document. Open (or create) a Powersheet document in your project and set its sheet configuration custom field to the name of the configuration you just created (rtm-sheet). You should see: When you open the document with Powersheet, it renders as a hierarchical sheet with four columns — UserNeed title and severity at the root level, and SystemRequirement title and severity as expandable child rows.
This configuration is intentionally minimal. Once it works, you can add more columns, define views, configure formatters, and introduce additional entity types one property at a time. See Incremental Configuration Approach for the recommended workflow.

​
Understanding root-level properties

The sheet configuration supports several root-level properties beyond columns and sources. You do not need all of these to start — columns and sources are sufficient for a working sheet:
PropertyPurpose
columnsColumn definitions with binding paths, titles, and display options
sourcesData source queries and expansion paths
viewsNamed column visibility presets for switching between analysis perspectives
formattersConditional formatting rules based on cell or row values
stylesReusable style definitions (colors, text decoration) referenced by formatters
columnGroupsVisual grouping of related columns with collapsible headers
sortByDefault client-side sort order by column and direction
renderersCustom rendering functions for specialized cell display
showGroupRowCounterWhether to display item counts on group rows (default: hidden)

​
Next steps