Workspace Definition File

# Introduction

# Why Workspaces?

Workspaces serve a crucial function in Modality. Modality compiles all the data you ever collect into a single database, building an empirical model of your system that allows you to ask complex questions, across disparate parts and over time.

Many tasks, however, concern a specific subset of this data. Workspaces let you create a view on your Modality database that only includes the relevant data for what you're trying to accomplish.

The way you filter your data with a workspace is by choosing what set of timelines to include. You specify this with any number of timeline filter expressions, boolean expressions based on timeline attributes. Details on writing these expressions can be found in the reference.

Since workspaces work by filtering, if you create a new workspace with a blank definition (or with no definition at all), it will include all data in Modality's database. You can also specify workspace metadata attributes as key-value pairs, helping you label and organize workspaces. All fields in a workspace definition are optional.

# Segmentation

The other powerful feature of workspaces is segmentation. Many use cases involve some related set of data that is split into discrete chunks. In one case, you could have a workspace for a test suite, and segments for each individual test case. In another, you could have a workspace for a specific test system, and segments for each discrete time you import data from that system.

Segmentation rules let you tell Modality how to split up your data. Modality will then automatically create segments in your workspace that you can analyze, individually or together.

# Workspace Definition File Fields

timeline-filters
string[]
Array of strings where each string is a timeline filter expression. Timeline filter expressions are boolean expressions to test whether a timeline should be included in the workspace. If all expressions return true for a given timeline that timeline is included. For details see the reference.
workspace-attributes
string[]
Array of strings where each string is a key-value assignment. These attributes will be stored as metadata on the workspace for workspace management. Note that these attributes do not require the _. prefix that timeline filter expressions do—they are just assigning a value to a key.
[[segmentation-rule]]
array of tables
Array of tables, each describing a segmentation rule. Segmentation rules specify timeline attributes for Modality to use to automatically split up your data into segments. You can then use the modality segment command to manage and select these for investigation. If you have multiple segmentation rules they will create multiple parallel sets of segments. In other words, each rule will produce a set of segments that cover all of the data in the workspace. Each rule must specify name and attributes.
  • name
    string
    Name of this segmentation rule. This is required.
  • attributes
    string[]
    Array of timeline attributes. Each timeline in the workspace will be assigned to a segment with the other timelines that have the same values for these attributes. This is required.
  • segment-name-template
    string
    Template for naming the segments generated by this rule. This is a template with string interpolation for attribute names placed in {} braces.

# Example Workspace Definition Files

# Simple Workspace

# Limit this workspace to data from the example system
timeline-filters = ["_.system = 'example-system'"]

# Metadata for workspace management
workspace-attributes = ["example = true", "complexity = simple"]

# No segmentation

# Drone Test Workspace

# NOTE: This could also be written as a single expression, like ["_.system = 'drone' AND _.operation = 'integration-tests'"]
timeline-filters = ["_.system = 'drone'", "_.operation = 'integration-tests'"]

# Metadata for workspace management
workspace-attributes = ["system = drone", "operation = integration-tests", "segmentation = test-case"]

# This rule segments on both run ID and test case ID. This way we will get a segment
# for each time each test case was run. If we only segmented by test case ID, we would get
# one segment for each test case containing all the timelines for all the times that test
# case has been run.
[[segmentation-rule]]
name = "test-cases"
attributes = ["run_id", "test_case_id"]
segment-name-template = "Test Case {timeline.test_case_id}"

← modality config →