In Harmoni, you can create new items, also known as User Created Axes (UCAs) or customized constructions, to suit your analysis and reporting requirements. You can use existing items in the project to create new items, or with user-enter values.

Integral to creating definitions is the expression editor. This is the interface where you create the definition for a new item. The expression editor uses items from the project tree to define the constructions and supports typing, and drag and drop to build the definitions.

Project owners create constructions that when published all users see, while Explorers and non-owner Creators can create private constructions that they own.

Creator
Explorer

Custom variable, created variable, UCA, User created axis

1. Expression Editor

The expression editor is the interface where you define a new item or construction.

To use the expression editor, you must be in edit mode.Learn more about edit mode.

For Project Owners: Click the edit pen
For Creators (non-owners) or Explorers: Click the design menu tab

Follow these steps to create and label a new item in the expression editor:

Switch to edit mode
Select a position in the project tree where the new item is required. If needed, the new item can be moved after creating it
Select a new item option under the construct heading in the design menu, e.g., new axis
A new, unlabeled axis appears in the tree
Type the new label name and press Enter
After pressing Enter, a new unlabeled element appears
Type the new element label and press Enter
It is important that you do not click anywhere before entering the element label, or the new axis will be removed
Once the new item is labeled, the Expression Editor opens, ready for the new definition

Note: Each new item type has a slightly different set of steps. Review the related article for specific instructions.

Name a New Item

You cannot name two axes or measures with the same name within the project tree. Harmoni provides a warning if you try to use an existing name and you will need to recreate the item. You can create elements with the same name.

If you are an Explorer or non-owning Creator, you may not see all the labels in the project tree as a Project Owner can hide or exclude items and these are not available in the published project. Harmoni will still warn you if you use an existing label created by the Project Owner, even those not visible.

As an Explorer or non-owning Creator you can create personal items that have the same name as other users' personal items. The conflict only arises with the Project Owner's project tree.

Rename an Item

You can edit a single label for a construction you own.

Switch to edit mode
Select your construction
Then double-click on the label, or press F2
The label becomes editable and you can update it
Once done, press Enter to accept the changes

If you double click on the label or press F2 when you have not switched to edit mode, Harmoni will not let you edit the label.

a. Typing into the Expression Editor

After you begin typing in the expression editor text box, a drop-down list displays the available matching axes within your project tree.

If you enter the exact axis match, the expression editor displays a "." (dot) in the drop-down list for you to select and then add the corresponding item into the definition.

As you type the label...

The possible options are displayed for selection in the drop-down list.
Use the arrow down key to highlight the option choice, and Enter to select it.
Existing elements in the project tree are used in the definition.
The most reliable way of including an item in a complex definition is by typing to display the list of matching labels and then selecting them from the displayed list.

Switch to edit mode
Select a position in the project tree
Click new axis
Type in the axis and first element name and press Enter
The expression editor opens

When I type the whole label name, it disappears from the drop-down list

If you type the whole axis name, e.g., Gender, you have typed what you need, so the option to select Gender is removed from the drop-down list. Continue writing your expression by selecting or typing the dot (.) and then select or type the element name.

Type whole label into ExpEditor.png

If you select the axis name from the drop-down list prior to typing the whole label, Harmoni automatically adds the dot (.) and you can type or select the element name.

b. Drag and Drop into the Expression Editor

An element can be defined using a single Axis.Element condition by dragging a single element into the expression editor.
Dragging in more than one element from the same axis into the definition assumes an OR relationship across elements.
Dragging in elements from different axes into the definition assumes an AND relationship.

To create a new item from an existing one, switch to project edit mode.
Select a position in the project tree.
Click "New Axis," name it and its first element, then press Enter.
Drag axes into the expression editor.
Elements from the same axis form OR; from different axes form AND relationships.
Apply the defined expression.

When an expression is saved, the quotes may be stripped. They’re only required when the label contains special characters such as commas, brackets, etc.

Please keep in mind that when elements contain characters that are used by Harmoni when creating definitions, for example, and/or, brackets ( ), or dots ., it is often easier to use drag and drop rather than typing when creating your construction. This will avoid any confusion in the definition and allow you to Save or Apply the expression.

2. Save and Apply Expression

Once you have defined your new items in the expression editor, Save Expression and Apply Expression become active. You will see the Save and Apply buttons turn green once Harmoni validates the conditions you have entered.

Apply Expression: Applies the definition and when you run an analysis, the data is available in the analysis table.
Save Expression: Saves your definition, but won't update data. If you save the expression and then create an analysis with the new item, no data displays in the analysis table. You must apply the expression to see the data in your analysis table.

To improve the workflow and efficiency when creating your custom variables, you can save multiple element definitions as you go, and delay the data processing until you are ready to apply the definitions.

Analysis data is only updated in new items when Apply Expression is applied to the axis.

When an expression is saved, the quotes may be stripped as they are only really required when the label contains special characters such as brackets.

If you are the Project Owner and have auto sync on, only Apply Expression is available as the expression is always applied to the data when sync is on.

🔗 Learn more about Auto Sync.

3. View the Definition

To view the definition of a constructed item, select the item and click library/editor in the action pane at the bottom left of the Harmoni screen. The editor opens and you can view the full definition.

If you are the owner of the construction, hover over the definition to reveal the EDIT button. Click EDIT to make changes to your constructed item. Note that if you are also the Project Owner, you need to click the project edit pen prior to editing the construction.

Select and element in a constructed item
Click the library/editor option
View the definitions for each element
Switch the edit pen on to edit the definition

Why can't I see the definition?

If the Project Owner hides items in a project tree and these items are used in a construction, a Creator (non-Owner) or Explorer with General Access can not see the definition in the editor.

If the Creator or Explorer has Preview Access, clicking the preview icon to view the unpublished view of the project allows the user to see the hidden items and all construction definitions.

Learn more about Preview Mode.

4. Update Broken Constructions

Constructions can sometimes break and this is most likely caused by data sources being removed or overwritten, resulting in items that were included in the construction no longer being available.

When replacing or removing data, you must proceed with caution. Review the Replacing or Removing Data Sources article to understand this fully.

The Project Owner can update these constructions with a revised definition. It is important that all elements in the construction are reviewed. Only when all elements in the construction are fixed can the construction be saved. If you cannot save the construction, ensure that you have checked every element.

Project Owners can also delete the broken construction, but it is important that they are sure the construction is not required.

Learn more about broken constructions.

5. Aggregation Type (Multi-level only)

When creating a measure in a multi-level project, you can select the aggregation type. This changes the way the data are aggregated together.

The default option is Sum, and when you create the new measure in the expression editor, you can change the aggregation type to Avg, Min, or Max.

Select one of the aggregation types available in the expression editor when defining your new measure. Learn more.

Where to from here?

Learn more about Constructions:

Related to

Using the Expression Editor

In this article