README - Platform — ContextQMD

Import from Unified Format Guide

Overview

The unified format represents workspace data in a hierarchical folder structure where:

Root directory contains space configurations (*.yaml) and their corresponding folders
Each space folder contains documents/issues (*.md) and their subdocuments/subissues
Documents/issues can have child items in similarly-named folders
File named settings.yaml is reserved and should not be used for spaces configuration
Files without required class property in frontmatter will be skipped

See the complete working example in the example workspace.

File Structure Example

workspace/
├── Documentation/
│   ├── Getting Started.md        # Standalone document
│   ├── User Guide.md             # Document with children
│   ├── User Guide/               # Child documents folder
│   │   ├── Installation.md
│   │   └── Configuration.md
│   └── files/                    # Attachments
│       └── architecture.png
├── Documentation.yaml            # Space configuration
├── Project Alpha/
│   ├── 1.Project Setup.md       # Issue with subtasks
│   ├── 1.Project Setup/         # Subtasks folder
│   │   ├── 2.Configure CI.md
│   │   └── 3.Setup Tests.md
│   ├── 4.Update Docs.md         # Standalone issue
│   └── files/
│       └── diagram.png          # Can be referenced in markdown content
└── Project Alpha.yaml           # Project configuration
├── QMS Documents/              # QMS documentation
│   ├── [SOP-001] Document Control.md           # Document template
│   ├── [SOP-001] Document Control/             # Template implementations
│   │   └── [SOP-002] Document Review.md        # Controlled document
│   └── [WI-001] Document Template Usage.md     # Standalone controlled document
└── QMS Documents.yaml         # QMS space configuration

File Format Requirements

All spaces files must be in YAML format
All document/issue files must include YAML frontmatter followed by Markdown content
Children documents/issues are located in the folder with the same name as the parent document/issue

Tracker Issues

1. Project Configuration (*.yaml)

Example: Project Alpha.yaml:

yaml

class: tracker:class:Project       # Required
title: Project Alpha               # Required
identifier: ALPHA                  # Required, max 5 uppercase letters/numbers, must start with a letter
private: false                     # Optional, default: false
autoJoin: true                     # Optional, default: true
owners:                            # Optional, list of email addresses
  - [email protected]
members:                           # Optional, list of email addresses
  - [email protected]
description: string                # Optional
defaultIssueStatus: Todo           # Optional

2. Issue (*.md)

Example: 1.Project Setup.md:

yaml

---
class: tracker:class:Issue        # Required
title: Project Setup              # Required
status: In Progress               # Required
priority: High                    # Optional
assignee: John Smith              # Optional
estimation: 8                     # Optional, in hours
remainingTime: 4                  # Optional, in hours
---
Task description in Markdown...

Issue Identification

Human-readable issue ID is formed by combining project's identifier and issue number from filename
Example: For project with identifier ALPHA and issue 1.Setup Project.md, the issue ID will be ALPHA-1

Allowed Values

Issue status values:

Backlog
Todo
In Progress
Done
Canceled

Issue priority values:

Low
Medium
High
Urgent

Documents

1. Teamspace Configuration (*.yaml)

Example: Documentation.yaml:

yaml

class: document:class:Teamspace   # Required
title: Documentation              # Required
private: false                    # Optional, default: false
autoJoin: true                    # Optional, default: true
owners:                           # Optional, list of email addresses
  - [email protected]
members:                          # Optional, list of email addresses
  - [email protected]
description: string               # Optional

2. Document (*.md)

Example: Getting Started.md:

yaml

---
class: document:class:Document    # Required
title: Getting Started Guide      # Required
---
# Content in Markdown format

Controlled Documents

1. Space Configuration (*.yaml)

QMS Document Space: QMS Documents.yaml:

yaml

class: documents:class:OrgSpace   # Required
title: QMS Documents              # Required
private: false                    # Optional, default: false
owners:                           # Optional, list of email addresses
  - [email protected]
members:                          # Optional, list of email addresses
  - [email protected]
description: string               # Optional
qualified: [email protected]   # Optional, qualified user
manager: [email protected]     # Optional, QMS manager
qara: [email protected]       # Optional, QA/RA specialist

2. Document Template (*.md)

Example: [SOP-001] Document Control.md:

yaml

---
class: documents:mixin:DocumentTemplate  # Required
title: SOP Template                      # Required
docPrefix: SOP                           # Required, document code prefix
category: documents:category:Procedures  # Required
author: John Smith                       # Required
owner: Jane Wilson                       # Required
abstract: Template description           # Optional
reviewers:                               # Optional
  - [email protected]
approvers:                               # Optional
  - [email protected]
coAuthors:                               # Optional
  - [email protected]
---
Template content in Markdown...

3. Controlled Document (*.md)

Example: [SOP-002] Document Review.md:

yaml

---
class: documents:class:ControlledDocument # Required
title: Document Review Procedure          # Required
template: [SOP-001] Document Control.md   # Required, path to template
author: John Smith                        # Required
owner: Jane Wilson                        # Required
abstract: Document description            # Optional
reviewers:                                # Optional
  - [email protected]
approvers:                                # Optional
  - [email protected]
coAuthors:                                # Optional
  - [email protected]
changeControl:                            # Optional
  description: Initial document creation
  reason: Need for standardized process
  impact: Improved document control
---
Document content in Markdown...

Controlled Document Code Format

Document code must be specified in file name: [CODE] Any File Name.md
If code is not specified for controlled document, it will be generated automatically using template's docPrefix and sequential number (e.g. SOP-99)
If code is not specified for template, it will be generated automatically as TMPL-seqNumber, where seqNumber is the sequence number of the template in the space

Run Import Tool

bash

docker run \
  -e FRONT_URL="https://huly.app" \
  -v /path/to/workspace:/data \
  hardcoreeng/import-tool:latest \
  -- bundle.js import /data \
  --user [email protected] \
  --password yourpassword \
  --workspace workspace-id

Limitations

All users must exist in the system before import
Assignees are mapped by full name
Files in space directories can be used as attachments when referenced in markdown content
Document codes (in square brackets) must be unique across all document spaces
Controlled documents must be created in the same space as their templates
Controlled documents can be imported only with Draft status