Managing Workspaces¶

Workspaces serve as repositories for storing and managing Actian DataConnect projects and their associated content. Each workspace contains three different types of resources: projects, folders, and files. Projects can be created from Project Explorer and may contain folders, files, and design artifacts (such as data quality designs) created within Actian DataConnect.

You can define multiple workspaces, and create multiple projects within those workspaces, to help efficiently organize your collateral. In addition to having multiple projects, each project can be stored in a different location in a file system. You can also create multiple workspaces and easily switch between them. The flexibility provided with workspaces, projects, and folders enables you to organize your files according to your requirements.

Key capabilities:

• Create new workspaces from empty folders
• Import existing workspaces with artifacts
• Switch between multiple workspaces seamlessly
• Sync with file system changes in real-time
• Organize projects with hierarchical folder structures

Default Workspace¶

When you install Actian DataConnect for the first time, a default workspace is automatically created for you at C:\Users\<username>\Actian\DataConnect\workspace. All projects and their associated content (folders and DataConnect design artifacts) are stored in this workspace.

This default location is fixed, but the workspace path is otherwise user-defined: for any workspace you create or import, you choose the folder yourself (see Creating a New Workspace and Importing an Existing Workspace).

You can define multiple workspaces and create multiple projects within these workspaces. You can also set up collaborative workspaces for team environments where multiple users need to access shared artifacts.

Understanding the Project Explorer¶

The Project Explorer is displayed on the left side of the editor and serves as the primary workspace management interface in Actian DataConnect. It displays folders, projects, and artifacts within the current workspace in a tree view and is used for navigation purposes.

You can collapse the Project Explorer with the Toggle Project Explorer icon in the editor toolbar for a distraction-free editing view, and reopen it from the Activity Bar.

From Project Explorer, you can perform the following actions:

• Create, edit, delete, open, close, rename, import, or export projects
• Create artifacts in projects such as data quality designs and schemas
• Edit, delete, duplicate, import, or export artifacts in existing projects
• Organize artifacts using folders for better project structure
• Navigate through your workspace hierarchy efficiently

Project Explorer Components¶

The Project Explorer interface has three main areas: the Header Bar, the toolbar and navigation icons (workspace selector, sync, create, search, and sort), and the Project Tree.

Header Bar¶

Displays the "Project explorer" title with a Network icon at the top of the panel. This header identifies the workspace navigation area in the left sidebar.

Toolbar and Navigation Icons¶

The icons in and around the Project Explorer header let you select the active workspace, refresh the tree, create items, and search or sort the workspace contents.

Available icons:

Icon	Description
	Workspace selector: A dropdown showing the active workspace, with options to: • Switch workspaces — select another workspace from the list • Create New Workspace… — initialize a workspace in an empty folder • Import Workspace… — register an existing folder that contains DataConnect artifacts • Delete a workspace — non-destructive; removes only the DataConnect registration (via the trash icon that appears on hover), so your files remain on disk
	Sync with filesystem: Scans the workspace folder for file changes (new, modified, deleted) and updates the Project Explorer tree — use it after files change outside DataConnect (other IDEs, file managers, version control). A spinning animation appears during the sync.
	Create new item: Opens a creation menu with options — New Project, Data Quality Design, Folder, Text File (see Context Menu Actions).
	Search: Filters the tree by artifact name across all projects, folders, and files in the active workspace, with live filtering as you type.
	Sort: Sets the order of items in the tree (default is Alphabetical A-Z): • Alphabetical (A-Z) • Alphabetical (Z-A) • Sort by most recent • Sort by order added

Project Tree¶

Structure: Hierarchical tree view displaying workspace contents.

Node types:

• Projects - Top-level containers for related artifacts (Package icon)
• Folders - Organizational containers within projects (standard folder icon)
• Files - Individual artifacts including:
  • Data quality designs (.dq files)
  • Schemas and other supported artifact types

Composite artifact handling: DataConnect uses paired files for artifacts: a primary file (e.g., Accounts.dq) and a runtime configuration file (e.g., Accounts.dq.rtc). The Project Explorer automatically hides .rtc files when the primary file exists, presenting them as a single logical unit.

Context Menu Actions¶

The Project Explorer provides two context menus:

• Plus (+) menu — the toolbar creation menu for adding new items (New Project, Data Quality Design, Folder, Text File)
• Item context menu — the actions for a selected project, folder, or file (open, new, rename, delete, move, copy path, and reveal in file explorer); opened from the three-dot (⋮) icon or by right-clicking

Plus (+) Menu - Creating New Items¶

Click the Plus (+) button in the Project Explorer toolbar to create new workspace items (artifacts, folders, and projects) without leaving the Project Explorer. The menu provides four options: New Project, Data Quality Design, Folder, and Text File.

New Project¶

Creates a top-level project container within the active workspace.

To create a new project:

1. Click the Plus (+) button in the Project Explorer toolbar
2. Select New Project from the dropdown menu
3. In the Create Project dialog:
   • Enter Project name (required field)
   • Optionally add Description for documentation purposes
4. Click Create

The new project folder is created at the workspace root level and appears immediately in the Project Explorer tree, ready to contain folders and artifacts.

Data Quality Design¶

Creates a data quality (.dq) artifact for defining data quality analysis, validation, and remediation rules.

To create a new data quality design:

1. Click the Plus (+) button in the Project Explorer toolbar
2. Select Data Quality Design from the dropdown menu
3. In the Create Data Quality Design dialog:
   • Select the Parent folder from the dropdown (lists all projects and folders in the workspace)
   • Enter the Data quality design name (required) - do not include the file extension
   • Optionally add a Description for artifact metadata
4. Click Create

The system creates two paired files in the selected folder: the primary file ([name].dq) and its runtime configuration ([name].dq.rtc). The design opens immediately in the Data Quality Designer.

Folder¶

Creates a subfolder within a project or another folder for organizing artifacts hierarchically.

To create a new folder:

1. Click the Plus (+) button in the Project Explorer toolbar
2. Select Folder from the dropdown menu
3. In the Create Folder dialog:
   • Select the Parent folder from the dropdown (a project or existing folder)
   • Enter the Folder name (required field)
4. Click Create

The new folder is created within the selected parent and appears immediately in the Project Explorer tree, available for organizing artifacts and nested subfolders.

Text File¶

Creates a plain text file as a generic artifact within a project or folder—handy for notes, README files, or other supporting content kept alongside your designs.

To create a new text file:

1. Click the Plus (+) button in the Project Explorer toolbar
2. Select Text File from the dropdown menu
3. In the Create Text File dialog:
   • Select the Parent folder from the dropdown (a project or existing folder)
   • Enter the File name (required), including the extension (for example, notes.txt)
4. Click Create

The new text file is created in the selected folder and opens immediately in the editor, ready for you to add content.

Item Context Menu¶

Open this menu by clicking the three-dot (⋮) icon on a hovered item, or by right-clicking the item — both open the same menu. The available actions adapt to the item type, as shown below for a project, a folder, and a file.

Open with behavior:

• Default editor: Marked with "(default)" label - this editor opens when you double-click the file
• Alternative editors: May be available depending on the file type
• Selection: Your editor choice persists for future opens of that artifact

Delete behavior:

• Simple files: Single file removed from file system
• Composite artifacts: Both files deleted together (e.g., design.dq + design.dq.rtc)
• Confirmation: Dialog shows all files to be removed

Rename behavior:

• Simple files: Single file renamed
• Composite artifacts: Both files renamed maintaining their pairing (e.g., old.dq → new.dq and old.dq.rtc → new.dq.rtc)
• Validation: Ensures unique names within the folder and validates file extensions

Move behavior:

• Opens a Move dialog where you select the destination folder, then click Move
• Composite artifacts: Both files move together (e.g., design.dq + design.dq.rtc), and the artifact's log is relocated as well

Keyboard Shortcuts and Mouse Interactions¶

Keyboard shortcuts:

Creating a New Workspace¶

When to create a new workspace: Starting fresh projects, organizing new data quality designs, or establishing clean environments for development.

Critical requirement: New workspaces must point to an empty folder - folders containing any files or subdirectories will be rejected. Use import existing workspace instead.

Use case: Greenfield projects, new development environments, isolated testing workspaces.

Prerequisites for Creating Workspace¶

Required:

• Empty folder on your local file system
• Read/write permissions on the target folder location
• Valid file path - accessible from the DataConnect application

How to Create a Workspace¶

To create a new workspace:

1. In the Project Explorer panel, click the workspace dropdown (shows current workspace name or "Select workspace...").

   The workspace dropdown menu opens, displaying available workspaces and management options.

2. Click Create New Workspace... from the dropdown menu.

   The Create New Workspace dialog opens.

3. Fill in the required fields:

   

   • Workspace Name (required): Enter a display name for UI identification. It cannot be empty or contain only whitespace; there are no length restrictions (reasonable name lengths recommended).
   • Workspace Folder (required): Enter or browse to select an empty folder path on your local file system. You can type the path manually or use the browse button (folder icon).

   Tip

   If you browse to select a folder and the workspace name field is empty, DataConnect will automatically populate the workspace name with the folder name.

4. Review your entries (workspace name and folder path), then click the Create Workspace button.

   DataConnect validates your entries against the rules listed in step 3. If validation fails, you'll see a specific error message indicating which rule was violated. Common validation errors:

   Error Message	Cause	Solution
   "Please provide both name and path"	Missing required field(s)	Fill in both Workspace Name and Workspace Folder fields

The new workspace becomes active in the Project Explorer, showing the default Project_1 folder and the default MacroDef.json macro file:

Available Actions After Workspace Creation¶

1. Create projects - Add top-level project containers for organization
2. Import existing workspaces - Register a folder that already contains DataConnect artifacts (such as .dq files)
3. Create new artifacts - Build data quality designs and other artifacts
4. Switch workspaces - Access other registered workspaces via workspace selector dropdown

Importing an Existing Workspace¶

When to import: Working with existing DataConnect artifacts from previous installations, shared repositories, version control, or team collaboration.

Key difference from creation: Import accepts folders that contain existing files - specifically designed for folders with DataConnect artifacts (.dq, .process, .map files).

Use cases:

• Migrating from previous DataConnect installation
• Cloning projects from version control (Git, SVN)
• Accessing shared team workspaces
• Recovering backed-up artifacts
• Working with existing data quality designs and projects

Prerequisites for Importing Workspace¶

Required:

• Existing folder containing DataConnect artifacts (such as .dq files and schemas)
• Read/write permissions on the folder and its contents
• Valid file path - accessible from DataConnect application

How to Import a Workspace¶

To import an existing workspace:

1. In the Project Explorer panel, click the workspace dropdown.

   The workspace dropdown menu opens, displaying available workspaces and management options.

2. Click Import Workspace... from the dropdown menu.

   The Import Existing Workspace dialog opens.

3. Fill in the required fields:

   

   • Workspace Name (required): Enter a display name for UI identification. It does not need to match the folder name, cannot be empty or contain only whitespace, and has no length or special-character restrictions.
   • Workspace Folder (required): Enter or browse to select a folder path that contains existing artifacts. Unlike workspace creation, this folder can contain files. You can type the path manually or use the browse button (folder icon).

   Tip

   If you browse to select a folder and the workspace name field is empty, DataConnect will automatically populate the workspace name with the folder name.

4. Review your entries (workspace name and folder path), then click the Import Workspace button.

   DataConnect validates your entries against the rules listed in step 3. If validation fails, you'll see a specific error message indicating which rule was violated. Common validation errors:

   Error Message	Cause	Solution
   "Please provide both name and path"	Missing required field(s)	Fill in both Workspace Name and Workspace Folder fields

   If validation passes, the system automatically:

   • Scans the folder and all subdirectories for DataConnect artifacts
   • Discovers supported file types (.dq, .process, .map, .rtc)
   • Registers found artifacts in the workspace database
   • Creates .metadata metadata folder (if it doesn't exist)
   • Activates the imported workspace (becomes the current workspace)
   • Populates Project Explorer with discovered hierarchy

   Your imported workspace is now registered, activated, and ready to use.

What Gets Imported - Artifact Discovery¶

Composite artifact handling: When both a primary file (e.g., MyDesign.dq) and its runtime configuration (e.g., MyDesign.dq.rtc) are present, they are automatically paired and displayed as a single logical artifact in the Project Explorer.

Available Actions After Workspace Import¶

1. View artifacts - Browse imported projects, folders, and files in Project Explorer
2. Edit artifacts - Open and modify existing data quality designs and other artifacts in respective editors
3. Create new content - Add projects, folders, and artifacts to the imported workspace
4. Sync with file system - Detect external changes using the Refresh button
5. Switch workspaces - Access other registered workspaces via dropdown
6. Continue team collaboration - Work with shared artifacts and commit changes

Best Practices for Workspace Import¶

Recommended practices for successful imports:

Switching Between Workspaces¶

Actian DataConnect supports multiple registered workspaces with instant switching between them. This enables working on different projects, environments (dev/test/prod), or client workspaces within the same application instance.

Common use cases:

• Switching between client projects
• Moving between development, test, and production environments
• Comparing implementations across different workspaces
• Context switching for multitasking

How to Switch Workspaces¶

To switch to a different workspace:

1. In the Project Explorer panel, click the workspace dropdown (displays current workspace name).

   The workspace dropdown menu opens, showing all registered workspaces with their names and paths.

2. Click the workspace you want to activate from the list.

   Project Explorer reloads with the new workspace contents. Switching is instant for small workspaces, but may take several seconds for large workspaces with thousands of artifacts.

Workspace States¶

Deleting a Workspace¶

Workspace deletion is non-destructive to artifact files. Only the database registration is removed. All artifact files (such as .dq files, .rtc files, and schemas) remain intact on the file system.

Common reasons to delete a workspace:

• Workspace no longer needed in DataConnect
• Cleaning up workspace list
• Removing duplicate registrations
• Decommissioning project references

How to Delete a Workspace¶

To delete a workspace:

1. In the Project Explorer panel, click the workspace dropdown.

   The workspace dropdown menu opens, showing all registered workspaces.

2. Hover over the workspace you want to delete in the dropdown list.

   A trash icon (🗑️) appears on the right side of the workspace entry.

3. Click the trash/delete icon.

   A deletion confirmation dialog opens displaying:

   • Message: "Delete workspace \"[workspace-name]\"?"
   • Warning: "This will remove the workspace from the database only. No files will be deleted."
   • Options: OK/Confirm (proceed) or Cancel (abort)

4. Click OK or Confirm to proceed with deletion.

   The system automatically:

   • Removes the workspace entry from DataConnect database
   • Removes the workspace from dropdown selector list
   • Prompts for new workspace selection (if deleted workspace was active)

What Gets Deleted vs. What Remains¶

Items deleted:

Items preserved:

Re-Importing a Deleted Workspace¶

If you accidentally deleted a workspace, you can restore it using the Import Workspace feature:

1. Click the workspace dropdown and select Import Workspace...
2. Select the same folder path as the deleted workspace
3. Enter a workspace name (can be the same or different from before)
4. Click Import Workspace

The system re-scans the folder and re-registers all artifacts. Your workspace is fully restored with all artifacts and folder structure intact.

Time to recover: Seconds to minutes depending on workspace size.

Synchronizing with the File System¶

The Project Explorer shows DataConnect's registered view of the workspace, which can drift from what's on disk when files change outside the app. Click the Sync with filesystem icon in the Project Explorer toolbar to reconcile the two.

When to sync — after files change outside DataConnect, for example:

• Edits, additions, or deletions made in another tool, a file manager, or the command line
• Version control operations (Git pull, merge, checkout)
• Changes to shared workspace files made by other team members

How to sync¶

1. In the Project Explorer toolbar, click the Sync with filesystem icon. It spins while DataConnect scans the workspace folder for files that were added or removed.
2. When the scan finishes, the tree refreshes and a toast reports the result:
   • Workspace synced — for example, "5 added, 2 deleted".
   • Sync completed with errors — the number of errors that occurred.

Out-of-sync files: A file marked out-of-sync was registered in DataConnect but is no longer found on disk. Restore it from backup, or remove it from the Project Explorer.

Workspace Folder Structure¶

Workspaces map directly to file system folders. The structure you create depends on your organization needs - you define the project folders and nested subfolders to organize your artifacts.

Sample workspace folder hierarchy:

The following shows a typical example structure. Your actual workspace structure will vary based on your projects and organization preferences.

my-workspace/                          # Workspace root folder
├── .metadata/                          # Internal folder (managed by DataConnect)
│   ├── logs/                          # Workspace-specific log files (dcim.log)
│   ├── drafts/                        # Unsaved draft content
│   └── conversations/                 # AI assistant chat history
│
├── CustomerArtifacts/               # Project folder (top-level container) - EXAMPLE
│   ├── Accounts.dq                    # Data quality design (primary file)
│   ├── Accounts.dq.rtc                # Runtime configuration (paired with .dq)
│   ├── Contacts.dq                    # Another data quality design
│   ├── Contacts.dq.rtc                # Paired runtime configuration
│   │
│   ├── Referenced_Files/              # Default location for DQ execution logs
│   │   ├── Accounts.log               # Run log for the Accounts design
│   │   └── Contacts.log               # Run log for the Contacts design
│   │
│   └── Schemas/                       # Nested subfolder
│       ├── CustomerSchema.xsd         # Schema definition file
│       └── ContactSchema.xsd          # Another schema file
│
└── SupplierArtifacts/               # Second project folder - EXAMPLE
    ├── Suppliers.dq                   # Data quality design
    ├── Suppliers.dq.rtc               # Paired runtime configuration
    │
    └── Validations/                   # Nested subfolder
        ├── SupplierValidation.dq      # Data quality design
        └── SupplierValidation.dq.rtc  # Paired runtime configuration

Folder Structure Concepts¶

Component definitions:

.metadata Folder Details¶

Internal structure and contents:

Critical warnings:

• Do not manually edit .metadata folder contents - can corrupt workspace
• Do not delete .metadata folder while workspace is registered - causes sync errors
• Do backup .metadata folder for disaster recovery

Composite Artifact File Pairing¶

Pairing mechanism: DataConnect automatically pairs primary artifact files with their runtime configuration files:

Pairing rules:

• Runtime config must have same base name as primary file
• Runtime config must have .rtc extension appended
• If .rtc file missing, primary file still appears but may have limited functionality
• If primary file missing but .rtc exists, artifact is invalid (out of sync)

Workspace Settings and Isolation¶

Isolation principle: Workspaces are completely independent - changes in one workspace do not affect others. Each workspace maintains separate artifact registries, settings, and states.

Workspace Independence¶

Isolation characteristics:

Implications:

• Creating artifacts in workspace A doesn't affect workspace B
• Deleting workspace A registration doesn't affect workspace B
• Settings changes in workspace A don't apply to workspace B
• Sync operations target only the active workspace

Workspace Logs¶

DataConnect creates workspace-specific log files for monitoring activity and troubleshooting:

• Log location: <workspace-path>\.metadata\logs\dcim.log
• Default workspace example: C:\Users\<username>\Actian\DataConnect\workspace\.metadata\logs\dcim.log
• Log rotation: When dcim.log reaches 2MB, it rotates to dcim.log.1, dcim.log.2, etc.
• Maximum files: Up to 7 rotated log files (10MB total size limit)
• Log level: Defaults to INFO. To capture more (or less) detail, set the DCIM_LOG_LEVEL environment variable to the desired level (for example, debug or trace) before starting DataConnect.

Quick Reference¶

Key characteristics¶

• Isolated (changes don't affect other workspaces)
• File-backed (direct folder mapping)
• Non-destructive deletion (files remain intact)
• Hierarchical (Projects → Folders → Artifacts)

When to use each operation¶

• Create: New projects, clean environments
• Import: Existing artifacts, migrations, version control, backups
• Switch: Moving between client projects or dev/test/prod environments
• Delete: Removing a workspace registration (files remain on disk)
• Sync: After external edits, Git operations, team changes

Critical warnings¶

• ⚠️ Never edit .metadata folder manually
• ⚠️ Deleting workspace keeps files (only removes registration)
• ⚠️ Sync after external file operations

Best practices¶

• Backup workspace folders regularly
• Use local storage for active development
• Organize with logical project hierarchies
• Sync before deployments/exports

Troubleshooting¶

See also¶

• Design Workbench — the full Design Workbench UI and how the Project Explorer fits into the overall interface.
• Settings — workspace-specific preferences, global settings, and customization options.
• Macro Manager — workspace-level macros, reusable configurations, and parameterized workflows.

By mastering workspace management, you gain full control over organizing, navigating, and maintaining your data quality designs and solutions in Actian DataConnect. Workspaces form the foundation for all other DataConnect operations - understanding them thoroughly enables efficient, scalable project management.