Package Creation Guide

A package is a ZIP archive consisting of mandatory and optional folders and files.

Mandatory components:

• workspace folder — required if the package is a workspace template. It contains JSON files describing the elements of the workspace template
• Setting ZIP folder — required for widgets or applications. It includes a code file (e.g., in JavaScript format) and a manifest file
• manifest file — a JSON file containing metadata about the package

Optional components:

• resources folder — contains system icons for the package
• ru and en folders — contain Russian and English localization content for the package description

resources Folder

The resources folder contains .png and .svg image files. To display system icons in the Marketplace, specify the image names in the "systems" block of the manifest.json file. If the package does not include a resources folder, the "systems" block remains empty, and the system default icon will be used in the Marketplace.

ru and en Folders

The ru and en folders may contain:

• doc.md — a Markdown-formatted file with a detailed description of the package
• An images subfolder containing .png and .svg images referenced in the doc.md file
• changelog.md — a Markdown-formatted file detailing changes made in the current version compared to the previous one

manifest File

An example of the manifest.json file:

{
    "manifest_version": "2",
    "author": "Operavix",
    "guid": "5096e32c-7e8a-4690-b742-caa94ff1b032",
    "name": "Workspace",
    "type": "workspace",
    "version": "1.0.0",
    "min_version_platform": "1.24.11.x",
    "max_version_platform": "1.25.02.x",
    "systems": [
        {
            "name": "image"
        }
    ],
    "description": {
        "ru": "Шаблон пространств",
        "en": "Workspace template"
    },
    "categories": {
        "ru": [
            {
                "name": "Пространство"
            }
        ],
        "en": [
            {
                "name": "Workspace"
            }
        ]
    },
    "dependency": [
        {
            "guid": "3245f02d-ab3c-4012-97e9-42327243ab9d",
            "version": "1.0.0"
        }
    ]
}

Explanation:

• "author": "Operavix" — package author
• "guid": "5096e32c-7e8a-4690-b742-caa94ff1b032" — GUID of the package
• "name": "Workspace" — package name
• "type": "workspace" — package type
• "version": "1.0.0" — package version
• "min_version_platform": "1.24.11.x" — minimum platform version that supports this package
• "max_version_platform": "1.25.02.x" — maximum platform version that supports this package
• "systems" — describes systems associated with the package
  • "name": "image" — filename (.png or .svg) located in the resources folder.
• "description" — short description of the package
  • "ru": "Шаблон пространств" — Russian localization of the description
  • "en": "Workspace template" — English localization of the description
• "categories" — categorization of the package
  • "ru" — Russian category name
  • "en" — English category name
• "dependency" — defines dependencies on other packages
  • "guid": "3245f02d-ab3c-4012-97e9-42327243ab9d" — GUID of the required dependency package
  • "version": "1.0.0" — required version of the dependency package

The max_version_platform field is managed by the package author. If incompatible platform changes affect package functionality:

1. Set the max_version_platform value in the current version to reflect the last supported platform version.
2. Upload a new package version compatible with the updated platform.
3. Ensure the new version's min_version_platform matches the platform version where these changes were introduced.

Package Lifecycle

The package lifecycle is defined in the "lifecycle" block of the manifest.json file. This feature is supported only for workspace templates and specifies commands executed during installation, update, disassembly, or removal ("install", "update", "disassemble" or "remove" respectively).

Example lifecycle configuration:

{
    "lifecycle": {
        "install": [
            {
                "cmd": "run_script",
                "key": "1",
                "type_execute": "async",
                "params": {
                    "param1": "test",
                    "param2": "example",
                    "param3": 2
                }
            },
            {
                "cmd": "sql",
                "query": "CREATE TABLE %s.tbl (c1 Nullable(String), c2 UInt64, c3 Nullable(String)) ENGINE = Memory;"
            },
            {
                "cmd": "run_script",
                "type_execute": "async",
                "key": "2"
            }
        ],
        "update": [],
        "disassemble": [],
        "remove": []
    }
}

Explanation:

• "install" — commands run after package installation. If an error occurs, installation is rolled back and an error message is displayed
• "update" — commands run after package update. The system uses instructions from the new package. If an error occurs, the update is canceled and an error message is shown
• "disassemble" — commands executed before disassembling the package
• "remove" — commands executed before removing the package

Supported Commands

workspace Folder

The workspace folder contains JSON files describing the elements of a workspace template. Examples include:

• bidata.json
• automation.json
• dashboard.json

{
    "schema_version": 1,
    "tables": [
        {
            "columns": [
                {
                    "name": "STEP",
                    "type": "Nullable(String)"
                },
                {
                    "name": "STEP_DATE",
                    "type": "Nullable(DateTime64(3))"
                },
                {
                    "name": "MONTH",
                    "type": "Nullable(Int64)"
                }
            ],
            "name": "log",
            "guid": "2006f59a-11f7-467c-b860-0b6cbcbbf3c1"
        },
    ],
    "processes": [
        {
            "time_column": {
                "column": "date_time_status",
                "table": "step_1"
            },
            "name": "New process",
            "guid": "7042ee73-45d5-4c6c-8bdf-43e3f8185fc6",
            "case_table_case_column": {
                "column": "order_number",
                "table": "step_2"
            },
            "case_column": {
                "column": "order_number",
                "table": "step_1"
            },
            "event_formula": "\"step_1\".\"action\""
        }
    ],
    "table_links": [
        {
            "second_column": {
                "column": "FIRST_NAME",
                "table": "original table_1"
            },
            "guid": "f14f1d6f-2280-4a8b-9514-a41f855d8091",
            "first_column": {
                "column": "FIRST_NAME",
                "table": "original table"
            },
            "direction": "DIRECTED"
        },
    ]
}

Settings Folder

The code file for a widget can contain any valid implementation.

Example of a manifest.json file for a widget:

{
  "api_version": 1,
  "name": {
    "en": "Pictures",
    "ru": "Изображения"
  },
  "uuid": "6f9bf5a6-273a-4087-a207-4fb169e02f9b",
  "entry": "index.js",
  "default_size_percentage": {
    "width": 60,
    "height": 20,
    "min_width": 8,
    "min_height": 4
  }
}

Explanation:

• "name" — widget name displayed in the dashboard editor
  • "en": "Pictures" — English package name
  • "ru": "Изображения" — Russian package name
• "uuid": "6f9bf5a6-273a-4087-a207-4fb169e02f9b" — unique widget identifier
• entry": "index.js" — filename containing the widget's code
• "width": 60 — default widget width (percentage)
• "height": 20 — default widget height (percentage)
• "min_width": 8 — minimum allowed width
• "min_height": 4 — minimum allowed width

For applications, only the entry point file needs to be specified in the manifest. Example:

{
  "entry": "index.js"
}

Requirements for Uploading Packages

Packages uploaded to the Marketplace or directly into a workspace must meet the following requirements:

• Packages must not be created on macOS machines
• The manifest.json file must be present and located at the root of the archive
• The GUID must follow the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and consist only of hexadecimal characters
• The package version must follow the x.x.x format
• The package type must be one of: widget, application, workspace
• The manifest.json file must include the following fields: systems (can be empty), author, manifest_version, name, guid, description, categories, type, version
• All filenames within the package must be in English
• Icon filenames in the resources folder must match the system names listed in the systems section of manifest.json. If no resources folder is provided, the system default icon will be used
• PNG icons must be 20x20 pixels
• The images folder must contain only .png and .svg files
• Image paths in documentation should omit the folder name — only the filename should be used. Example: ![image](image_name.png)
• The archive root must contain the actual package content: either application.zip, widget.zip, or a workspace folder
• Files changelog.md, doc.md, and the images folder are optional
• Only ru and en localizations are currently supported. While other languages may be included in the manifest without causing upload errors, they will not be displayed in the system
• The dependency field in the manifest must specify the GUID and version of any required dependent packages. If a dependency is missing from the Marketplace, the upload fails
• If the package contains a workspace folder, the manifest_version in manifest.json must not be 1
• Both min_version_platform and max_version_platform fields are required, and the patch version must use the format x (e.g., "min_version_platform": "1.24.11.x")