Creating Dimension Groups

1: Summary

The dimensionGroup transform is used to organize related questions into dimensions for scoring and reporting. A dimension typically represents a theme—like “Well-being” or “Engagement”—and can contain multiple survey questions.

When you define a dimensionGroup, SmartHub automatically creates three linked tables:

• <name>_dimensions

• <name>_questions

• <name>_dimension_question (join table)

These allow you to analyze both dimension-level and item-level data.

2: Declaring a Dimension Group

dimensionGroup #dg1 {
  parent: .response:
  dimensions {
    // dimension and compoundDimension definitions
  }
  questions {
    // question metadata
  }
}

2.1: Properties

Property	Description
parent	Table that this group is created within (e.g., .response: or a loop).

3: Defining Dimensions

Each dimension contains a list of questions and optional extra fields:

dimension #wellBeing {
label: "Well-Being"
questions: .response:PH22347, .response:PH22348
values {
type: "composite"
isPrimary: false
includeHXWidget: true
description: "Perceptions of physical, mental, and emotional health."
}
}

4: Creating Compound Dimensions

Compound dimensions combine other dimensions into a higher-level roll-up:

compoundDimension #resilience {
  label: "Resilience"
  dimensions: @resActivation, @resDecompression
  values {
    type: "overall"
    isPrimary: false
    includeHXWidget: true
    description: "Ability to recover from or adjust to stress in the workplace."
  }
}

Tip: Define regular dimensions before referencing them in compound dimensions.

5: Adding Extra Variables with action create

You can define additional fields to store metadata in both dimensions and questions:

action create {
  variable boolean #includeHXWidget { }
  variable opentext #type { length: 50 }
  variable opentext #description { length: 500 }
}

These will appear as columns in the _dimensions or _questions tables.

6: Declaring Questions

Use the questions block to assign metadata to individual survey questions:

question #PH1006 {
  values {
    extraVariableOne: true
    extraVariableTwo: "pitPhysician"
  }
}

Order matters: The order of question entries determines the row order in the _questions table. If a question is not listed here, but is used in a dimension, it will appear in the _questions table in the order that it is in the CDL document

7: Full Example

dimensionGroup #dg1 {
  parent: .response:
       dimensions {
    action create {
      variable boolean #includeHXWidget {}
      variable opentext #type { length: 50 }
    }
       dimension #resActivation {
      label: "Resilience Activation"
      questions: .response:PH20191, .response:PH6346
      values {
        type: "composite"
        includeHXWidget: true
      }
    }
        compoundDimension #resilience {
      label: "Resilience"
      dimensions: @resActivation
      values {
        type: "overall"
        includeHXWidget: true
      }
    }
  }
         questions {
    action create {
      variable boolean #extraVariableOne {}
    }
       question #PH20191 {
      values {
        extraVariableOne: true
      }
    }
          }
}

8: Best Practices

• Group questions by concept or theme.

• Use compound dimensions for higher-level rollups (e.g., combining Engagement and Satisfaction).

• Keep labels user-friendly—they’ll appear in reports and exports.

• Leverage action create to tag and filter dimensions later in dashboards.