mirror of
https://github.com/hcengineering/platform.git
synced 2025-03-15 18:54:14 +00:00
…
|
||
---|---|---|
.. | ||
example-workspace | ||
README.md |
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 issue1.Setup Project.md
, the issue ID will beALPHA-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
, whereseqNumber
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