platform/dev/import-tool/docs/huly

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:

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
  - john.doe@example.com
members:                           # Optional, list of email addresses
  - joe.shmoe@example.com
description: string                # Optional
defaultIssueStatus: Todo           # Optional

2. Issue (*.md)

Example: 1.Project Setup.md:

---
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:

class: document:class:Teamspace   # Required
title: Documentation              # Required
private: false                    # Optional, default: false
autoJoin: true                    # Optional, default: true
owners:                           # Optional, list of email addresses
  - john.doe@example.com
members:                          # Optional, list of email addresses
  - joe.shmoe@example.com
description: string               # Optional

2. Document (*.md)

Example: Getting Started.md:

---
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:

class: documents:class:OrgSpace   # Required
title: QMS Documents              # Required
private: false                    # Optional, default: false
owners:                           # Optional, list of email addresses
  - john.doe@example.com
members:                          # Optional, list of email addresses
  - joe.shmoe@example.com
description: string               # Optional
qualified: john.doe@example.com   # Optional, qualified user
manager: jane.doe@example.com     # Optional, QMS manager
qara: bob.smith@example.com       # Optional, QA/RA specialist

2. Document Template (*.md)

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

---
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
  - alice.cooper@example.com
approvers:                               # Optional
  - david.brown@example.com
coAuthors:                               # Optional
  - bob.dylan@example.com
---
Template content in Markdown...

3. Controlled Document (*.md)

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

---
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
  - alice.cooper@example.com
approvers:                                # Optional
  - david.brown@example.com
coAuthors:                                # Optional
  - bob.dylan@example.com
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

docker run \
  -e FRONT_URL="https://huly.app" \
  -v /path/to/workspace:/data \
  hardcoreeng/import-tool:latest \
  -- bundle.js import /data \
  --user your.email@company.com \
  --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