# Matrix Configuration ## Create A New Matrix The **Matrix Configuration** page allows users to define the structure and layout of a matrix. You can access this page in different ways depending on your environment: * **Wave Embedded**:\ Access Matrix Configuration by clicking the **Add New** button and selecting **Matrix**, or directly clicking the **Matrix Wizard** button from the Wave Dashboard.

* **Wave Extension**:\ Go to the **Matrix** screen and click **Create New Matrix** to begin configuring a new matrix.

> **Notes:** This page is only for **Designer** or **Admin** role. ## 1. Matrix Details The **Matrix Details** section lets Designers configure the structure and data sources of the matrix. ### Matrix Title The title is automatically generated based on the selected **Row** and **Column** objects, followed by the word “Matrix” (e.g., *Account and Opportunity Matrix*). Designers can manually rename the Matrix title as needed. ### Layout Configuration Define the key components of your matrix by selecting objects and fields for each axis: * **Row (Y-axis)** ![](https://2237973035-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F65f4C4H8V5e0YV342mwp%2Fuploads%2FH6U7jgLXhOTWT2KXjGxn%2FRow%20Icon.png?alt=media\&token=c5f34b95-f91c-47a5-ba7f-d76cc7e6e16d)**:**\ Choose the object and its fields to represent matrix rows. * **Column (X-axis)** ![](https://2237973035-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F65f4C4H8V5e0YV342mwp%2Fuploads%2F5Mbqpd8JptWoI5i1IolL%2FColumn%20Icon.png?alt=media\&token=6099a7c3-baaf-4ed0-be40-441002878c54)**:**\ Select the object and a single field to represent columns. > **Note:** Supported field types for the X-Axis are *Date*, *Lookup*, and *Picklist*. * **Data** ![](https://2237973035-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F65f4C4H8V5e0YV342mwp%2Fuploads%2FPxk7GdZuZmipJslXi1F0%2FData%20Icon.png?alt=media\&token=714bb4a2-74c4-4570-ab37-a8576e1ec27a) **(Measure):**\ Specify the data source and fields that will populate the matrix values. * **Type: Existing** – Uses the **same object** as selected for the X-axis. * **Type: New** – Lets user select a **different object**, enabling **two-object** or **three-object** matrices, depending on the object combination.

*** ## **2. Data Config** The **Data Config** section empowers Designers to shape how data is structured, calculated, and presented in the matrix. It includes tools to: * Define data aggregation and editing behavior through [**Configure Measure**](#configure-measure) * Control the runtime experience of viewing and editing records with [**Detail Layout**](#detail-layout) * Customize how data fields are laid out using [**Matrix Orientations**](#matrix-orientations) Together, these settings offer powerful flexibility to tailor the matrix to your business needs and user workflows.

### Configure Measure The **Configure Measure** section allows Designers to define how data is calculated, displayed, and edited within the matrix. It includes settings for aggregating data, controlling how changes are saved, and customizing the behavior and appearance of each field. #### **Data Aggregation** Choose how values are pulled from the dataset. * **Combine Value** – Aggregates all related records using functions like **Sum**, **Average**, or **Count**. * **First Match** – Displays the value from the first matching record. #### **Save Options *****(only for Combine Value)*** Decide how edited values are distributed across records. * **Weighted Average** * **Equal Distribution** #### **Data Fields** The **Data Fields** section lets Designers customize how each field behaves and appears within the matrix. These settings control display preferences, input rules, formatting, default values, and field behavior during runtime. #### Field Name * Click to rename the field (must be unique; max 25 characters). * Use **Revert** to reset the name to the system default.

#### Group Functions(for Combine Value) Define how data is summarized when combining multiple records: * **Sum** – Adds up numeric values. * **Average** – Calculates the average value. * **Count** – Counts the total number of records. * **Required** * Marks a field as mandatory. Users must enter a value before adding or saving a record. #### Dynamic Matrix Field Controls whether the field appears in the **Dynamic Measures** tab at runtime. * ✅ **Checked** – The field appears in the Dynamic Measures tab in runtime and users can toggle its visibility as needed. * ⬜ **Unchecked** – The field appear in the Dynamic Measures tab, but users cannot toggle its visibility during runtime.

#### Hidden Field Hides the field from the matrix view by default. * If a field is both **Hidden** and a **Dynamic Matrix Field**, it stays hidden initially but can be added by the user at runtime through **Dynamic Measures**. **Field Visibility Scenario:**

Hidden	Dynamic Matrix Field	Matrix View	Dynamic Measures
✅	✅	❌ Not shown	✅ Available (unchecked)
✅	❌	❌ Not shown	❌ Not available
❌	✅	✅ Shown	✅ Available
❌	❌	✅ Shown (fixed)	❌ Not available

Configure the Hidden Field and Dynamic Matrix Field

#### Total The **Matrix Totals** feature allows you to display automatic totals directly within your matrix grid, giving you instant insights into your data without additional calculations. * **Configurable Display:** Choose up to **three columns** to show totals during configuration. * **Instant Calculation:** Totals are automatically generated based on the values in your data columns **Display Behavior** * **Show Totals Visibility:** The *Show Totals* checkbox is hidden if: * The maximum column limit is reached, or * The selected field in **Data Config** is non-numeric. * **Default Position:** The Totals column is pinned to the right side by default. * **User Movement:** If the user moves the Totals column to the left (using the *Move to Left* icon), it appears between the Y-axis columns and the historical columns and becomes unpinned. * **Toggling:** Users can toggle between the two positions (pinned right vs. unpinned left). * **Refresh Behavior:** The Totals column returns to its default right-pinned position when the user refreshes or re-runs the matrix. **Notes** — When the matrix is first rendered and historical columns are hidden, their data isn’t initially loaded. As a result, the Totals column doesn’t include hidden historical data at first. Once the user expands the hidden historical columns, the data is fetched, and from that point onward, the Totals column reflects historical data, even if those columns are later collapsed again.

#### **Read-Only** * Prevents users from editing the field in the matrix. Display only. #### **Format Cell** Applies to **Number**, **Currency**, and **Decimal** fields. * **Decimal Control** – Set number of decimal places. * **Unit Scaling** – Display values in thousands, millions, etc. **Example:** * Field value: `1.345` * Decimal Places: `3` * Unit Scaling: `Millions` * Displayed as: `1.345` → Represents `1,345,00`

#### **Default Value** Allows setting predefined values for **new records only**. These values are not applied to existing records.

### Detail Layout Use the **Detail Layout** settings to control how users view and edit matching records within the matrix during runtime.

#### **Show Detail View Toggle** Enable or disable the **Detail View** in runtime. * **Enabled** – Users can access the DDV to view and edit records. * **Disabled** – The DDV will be hidden from runtime. #### **Cell Behavior Options** Set how users can edit records: | Option | Description | | ---------------- | ---------------------------------------------- | | Both | Users can edit inline or open the DDV. | | Edit in DDV only | Records can only be edited in the detail view. | | Edit Inline only | Users edit directly in the matrix grid. |

#### Records Grid and Detail View View and manage matching records in a records grid. Click a record to open its detailed layout to review and edit. * **Configure Record Grid**\ Customize the fields shown in the record grid: * Add or remove fields. * Rearrange column order to prioritize important data. * **Configure Detail Layout**\ Design how fields appear in the record detail view: * Add or remove fields. * Rearrange layout to suit your workflow.

### Matrix Orientations Choose how your data is arranged in the matrix by selecting an orientation that best fits your analysis: * **Horizontal Orientation** – Fields from the data object are displayed as columns. * **Vertical Orientation** – Fields from the data object are displayed as rows. This flexibility helps you customize the matrix layout based on the structure of your data and how you prefer to analyze it.

**In Runtime:**

*** ## 3. Timeline – Matrix Configuration (Visible Only for Date Fields) This tab lets you choose between **Straight Line** and **Telescope** views to display data over time. > *Visible only when a Date field is selected for the Column (X-axis)* The **Timeline** tab allows Designers to display data over time using structured or dynamic intervals. This configuration becomes available only when a **Date field** is selected for the column.

**Example:**

Timeline - Telescoping for 3 months and 3 quarters

### Choose Timeline Methods * **Straight Line:**\ Displays data chronologically based on the selected interval. * **Telescope:**\ Enables a dynamic, rolling time window (e.g., *Past 3 Months*, *Current Quarter*, or *All Years*), ideal for trend analysis. * **0** is **allowed** in *Telescoping Timeline* only if at least one of the three values (Months, Quarters, Years) is greater than 0 or set to “All.” * **0** is **not allowed** in *Relative Date* configurations.

### Time Horizon * **Absolute:**\ Pick a fixed start date using a calendar. * **Relative:**\ Dynamically define time ranges using customizable logic. * **Default:** Uses "is on or before" with a default value of *1 month*. * **Dual Parameters:** Optionally include both "is on or before" and "is on or after" to define a precise rolling range. * The following are the **maximum allowed values** for each relative calendar interval:

Interval	Max Value
Days	365
Weeks	52
Months	120
Quarters	60
Fiscal Quarters	60
Years	15
Fiscal Years	15

This ensures consistent and accurate results when defining relative start dates.

#### Historical View Easily track and compare your past data with the new **Historical View** option. * **Show Past Period (Relative only):** Display historical data for up to **18 months**. * **Hide Past Month by Default:** Past data is hidden initially; click the icon to toggle visibility. * **Always Visible:** Keep selected data visible, even when hidden, with options **M**, **M-1**, or **M-2**. * **Read Only:** Lock past data to prevent any edits. This feature helps you analyze trends over time while keeping your data secure and organized. #### Special Rules **Relative Time Horizon** * If **Straight Line Interval** = *Exact Date* → Historical options are **not supported**. * If **Timeline Method** = *Telescope* → Telescoping starts from the current period, and Historical data will be **monthly only**. **Absolute Time Horizon** * If **Straight Line Interval** = *Exact Date* → Historical options are **not supported**. * If **Timeline Method** = *Telescope* → Historical options are **not supported**.

*** ## 4. Filters – Record Selection The **Record Selection** feature lets you filter and refine the data shown in the Matrix based on the Row (Y-axis) and Column (X-axis) object selections. ### Accessing Record Selection Click the **Filter** button in the Matrix to open the **Record Selection** screen. You’ll see two sections: * **Initial Selection** – For the first object. * **Subsequent Selection** – For the second object. If neither selection has been configured, these sections appear greyed out and you will not be able to run the Matrix.

#### Switch Axis ![](https://2237973035-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F65f4C4H8V5e0YV342mwp%2Fuploads%2FhV8LIA0pmDCF32gvEaRV%2FUser%20Selection%20Toggle%20Switch%20Matrix.png?alt=media\&token=45ddd6da-021a-45d2-ab7b-29ca6471b2c9) A toggle button allows you to switch the Row and Column object positions. This can help you adjust how records are filtered and presented.

### Configuring Record Selection Clicking **Configuration** opens the **Search Configuration** window, where you define how records are searched and filtered. {% stepper %} {% step %} **Choose Object Type** You can choose the source object for the selection: * **Current Object** (default): The object used when the Matrix was created.

* **Parent Object**: A parent of the current object. Selecting this updates the available fields based on the object relationship.

{% endstep %} {% step %} **Select Object Fields** Once the object is selected: * Use the **search bar** or scroll to locate fields. * Select fields to display in the record selection popup. * Reorder selected fields — the order affects how fields appear during record selection. * Selected fields are marked with ✔️ and assigned a position number.

{% endstep %} {% step %} **Filters and Filters (Current Object)** The **Filters** section allows you to define how records are filtered before being displayed in the Matrix. When a **Parent Object** is selected as the initial (Y-axis) object, an additional button—**Filters (Current Object)**—will appear.\ This option allows you to apply filters on the **child (current)** records based on the parent records you've selected. * **Filters**: Use filters to narrow down the records for the selected object (either the **Current Object** or its **Parent** * **Filters (Current Object)**: This option appears only when you’ve selected a **Parent Object**. It lets you filter **child records** based on the values from the linked **parent record**.

This dual-filter setup provides greater control over what data appears in the Matrix, especially in parent-child object relationships. {% endstep %} {% step %} **Add Search Filters (Optional)** If you want to pre-filter data: * Enable the **Search** checkbox for a field. * Choose a **condition** (e.g., Starts With, Equals). * Enter a **default value**.

When **Search** is enabled for a field, it also enables **filtering for Standard Users** in the Record Selection window. This allows Standard Users to filter records based on those fields during Matrix runtime. {% endstep %} {% step %} **Choose Record Selection Mode** Decide how many records users can select during runtime: * **Single** – Only one record can be selected. * **Multi** – Multiple records can be selected.

{% endstep %} {% step %} **Linking and Filtering Between Objects (Subsequent/X-Axis Selection)** After configuring the **Initial Selection** (Y-axis object), click **Next** to set up the **Subsequent Selection** (X-axis object). By default, the X-axis is **linked** to the Y-axis. This means the records available for the X-axis are filtered based on what you selected in the Y-axis. * For example, if the Y-axis is **Schedule Plan** and the X-axis is **Scheduled Items**: * **Linked**: Only **Scheduled Items** related to the selected **Schedule Plan** records will appear. * **Unlinked**: All **Scheduled Items** will be shown, regardless of which **Schedule Plan** records were selected. You can choose to **unlink** the objects if you prefer to configure filters independently for each axis.

{% endstep %} {% step %} **Show Selection Toggle** Click **Show Selection** to display the list of fields for the **Subsequent Selection** (X-axis object).\ This enables a second record selection window—allowing users to choose records based on the X-axis object, similar to how the Y-axis (Initial Selection) works. If **Show Selection** is disabled, users will only see the record selection window for the Y-axis object. Once enabled, the steps are the same as the initial selection as the above steps (**Step 1 to Step 5**).

{% endstep %} {% step %} #### Final Step – Submit * Review your configuration. * Click **Submit** to apply the filter settings and return to the Matrix.

**Record Selection Screen After Filter Configuration**\ Once the Designer has configured the Filters, the Record Selection section updates to display only the records that match the defined criteria.

{% endstep %} {% endstepper %} *** ## 5. Display Options The **Display Options** section provides Designers with powerful tools to control the visual presentation and organization of Matrix data. It includes four configuration tabs: **Conditional Formatting**, **Sort**, **Column Group**, and **Layout** — giving you greater flexibility to customize how your data is grouped, sorted, styled, and displayed. ### **Conditional Formatting** Customize how your Matrix data is visually represented using separate formatting settings for the **Y-Axis** and **Data Fields**: **Y-Axis Formatting**\ Apply one of the following styles to values on the Y-axis: * **Single** – Apply formatting to individual values. * **Group** – Apply shared formatting across grouped values. * **Color Bar** – Use color gradients or bars to visually represent value intensity. **Data Field Formatting**\ Apply the same set of formatting options to any Data field: * **Single**, **Group**, or **Color Bar** – enabling contextual formatting to highlight trends or patterns in your data. This separation allows for precise and flexible visual enhancements based on your analysis needs.

### Known Issue **Issue**: In Matrix Configuration Mode, applying **Conditional Formatting** using **‘is any of’** or **‘is none of’** conditions on **Date** or **DateTime** fields causes the **Matrix to fail to render completely**. Users cannot see or interact with the Matrix. **Workaround**:\ Open the Matrix in Matrix Configuration Mode and delete the Conditional Formatting rule applied to the Date/DateTime field under Display Option section. > ℹ️ **Recommendation**: Until the issue is fixed in an upcoming release, avoid applying ‘is any of’ or ‘is none of’ conditions on Date/DateTime fields in Conditional Formatting. ### **Sort** The **Sort** tab enables users to define multiple sorting conditions for Matrix objects on the **Y-axis**. * Supports full flexibility with **no limit on the number of sort levels**. * Works similarly to sorting behavior in **Wave Grid**. * Lets Designers organize complex data views exactly as needed for clarity and comparison.

### Column Group The **Column Grouping** tab allows Designers to visually organize Y-axis fields into grouped sections. This helps users quickly understand how related data are structured within the Matrix.\ Learn more about configuring column group [here](https://docs.valorx.com/valorx-wave/wave-data-management/managing-grid-data/column-group).

### Layout The **Layout** tab allows Designers to customize the appearance of the Matrix for better readability and a polished presentation. #### Column Freeze Designers can freeze the **Y-axis** column to either the **left** or **right** side of the Matrix. This ensures important reference columns remain visible while scrolling horizontally. #### Row Height Choose from predefined row height options — **Short**, **Medium**, **Tall**, or **Extra Tall** — to improve data visibility. You can also enable **Auto Size Column** to automatically adjust the width based on content. For more details, see [Auto Size Columns](https://docs.valorx.com/valorx-wave/wave-data-management/managing-grid-data#auto-sizing-columns).

#### Resizable Columns You can resize both **Y-axis** and **Data-axis** headers to fit your layout needs. * **Expanded View**: Click **Expand** to open a resizing dialog for precise adjustments. Any changes made can be saved as layout preferences. * **Smart Display**: Header text wraps neatly (up to three lines for Y-axis and two for Data-axis) and automatically hides icons when space is limited. * **Consistent Formatting**: Progressive font and margin adjustments with “...” truncation maintain a clean, professional appearance. These layout options provide greater flexibility and control, helping you design clear, well-structured Matrices even for large or dense datasets.

*** ## 6. Manage Access The **Manage Access** settings allow Admins and Designers to control who can access the Matrix and what actions Standard Users are allowed to perform at runtime. This section contains two key tabs: **Users** and **Matrix Control.** ### Users Tab Use this tab to define which users can access the Matrix. **Allow All Users** * Grants access to *all users*. * No further configuration is needed. **Select Specific Users** * Restricts access to only selected users. > 🔔 *Note: If “Allow All Users” is selected, everyone automatically gains access.* * **Allow All Users** – Grant access to everyone. * **Selected Users** – Restrict access to only selected users.

#### ✅ To Assign Access to Specific Users: 1. Choose **Selected Users** from the access options. 2. Click the **Add More** button.\ A **Select Users** window will appear. 3. Search for users using the search bar or scroll through the list. 4. Select the desired users. 5. Click **Assign** to grant them access. > 🔔 If you choose **Allow All Users**, no further action is needed—all users will automatically have access.

To remove a user's access to a Matrix, click the **trash icon** (🗑️) under the **Action** column, then click **Save** to apply the changes.

### Matrix Control Tab This tab provides fine-grained control over how **Standard Users** can interact with the grid at runtime. **Field Permissions** * ✅ Allow adding and removing Y-axis fields * ✅ Allow adding and removing Data fields * ✅ Allow rearranging fields Y-axis and Data fields **Record Permissions** * ✅ Allow adding Data record **Display Options** * ✅ Allow editing Y-axis conditional formatting * ✅ Allow editing Data conditional formatting * ✅ Allow editing column grouping * ✅ Allow freezing/unfreezing columns * ✅ Allow editing sort

**Note:** * In **Wave Embedded**, click **Save Matrix** to save your configuration and **Save and Surf** to run the matrix runtime. * In **Wave Extension**, click **Save** to save changes and use the **Run** button to launch the matrix in runtime.