Инструкция по созданию пакета

Пакет — это zip-архив, состоящий из обязательных и необязательных папок с файлами.

Обязательные:

• Папка workspace, если это шаблон пространства. Она содержит файлы в формате JSON с описанием элементов шаблона пространства
• ZIP-папка с настройками, если это виджет или приложение. Она содержит файл с кодом для работы виджета, например, формата JS (JavaScript) и файл manifest
• Файл manifest в формате JSON, который содержит информацию о пакете

Необязательные:

• Папка resources, которая содержит иконки систем пакета
• Папки ru и en, которые содержат русскую и английскую локализацию описания пакета

Папка resources

Папка resources содержит файлы формата .png и .svg. Чтобы в Маркетплейсе у пакетов отображались иконки систем, укажите названия изображений в файле manifest в блоке "systems". При отсутствии в пакете папки resources блок "systems" остается пустым и в Маркетплейсе используется системная иконка.

Папки ru и en

Папки ru и en могут включать в себя:

• Файл doc.md — файл формата Markdown, который содержит развернутое описание пакета
• Папку images с изображениями формата .png и .svg, которые указываются в файле doc.md
• Файл changelog.md — файл формата Markdown, содержащий информацию об изменениях в пакете по сравнению с предыдущей версией

Файл manifest

Пример содержимого файла:

{
    "manifest_version": "2",
    "author": "Infomaximum",
    "guid": "5096e32c-7e8a-4690-b742-caa94ff1b032",
    "name": "Пространство",
    "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"
        }
    ]
}

где:

• "author": "Infomaximum" — автор пакета
• "guid": "5096e32c-7e8a-4690-b742-caa94ff1b032" — GUID пакета
• "name": "Пространство" — имя пакета
• "type": "workspace" — тип пакета
• "version": "1.0.0" — версия пакета
• "min_version_platform": "1.24.11.x" — минимальная версия платформы, в которой поддерживается пакет
• "max_version_platform": "1.25.02.x" — максимальная версия платформы, в которой поддерживается пакет
• "systems" — блок описания систем пакета
  • "name": "image" — имя файла .png или .svg в папке resources
• "description" — блок краткого описания пакета
  • "ru": "Шаблон пространств" — русская локализация описания пакета
  • "en": "Workspace template" — английская локализация описания пакета
• "categories" — блок описания категорий пакета
  • "ru" — русская локализация названия категории
  • "en" — английская локализация названия категории
• "dependency" — блок описания зависимости текущего пакета от другого
  • "guid": "3245f02d-ab3c-4012-97e9-42327243ab9d" — GUID пакета, от которого зависит текущий
  • "version": "1.0.0" — версия пакета, от которого зависит текущий

За параметр max_version_platform отвечает автор пакета. Если в системе произошли несовместимые изменения, которые влияют на работу пакета:

1. Укажите в текущей версии значение max_version_platform, соответствующее поддерживаемой версии платформы.
2. Загрузите в систему новую версию пакета, которая учитывает изменения платформы.
3. Убедитесь, что в новой версии пакета параметр min_version_platform совпадает с той версией, в которой эти изменения появились.

Жизненный цикл пакета

Жизненный цикл пакета описывается в блоке "lifecycle" файла manifest.json. Этот блок поддерживается только для шаблонов пространств и содержит команды, которые система выполняет при установке, обновлении, разборе или удалении пакета ("install", "update", "disassemble" или "remove" соответственно).

Пример жизненного цикла пакета в файле manifest.json:

{
    "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": []
    }
}

где:

• "install" — команды выполняются после установки пакета. Если в процессе возникает ошибка, установка отменяется и отображается сообщение об ошибке
• "update" — команды выполняются после обновления пакета. Система использует инструкции из нового пакета. Если в процессе возникает ошибка, обновление отменяется и отображается сообщение об ошибке
• "disassemble" — команды выполняются перед разбором пакета
• "remove" — команды выполняются перед удалением пакета

Поддерживаемые команды

Папка workspace

Папка workspace содержит файлы формата JSON с описанием элементов шаблона пространства. Примерами файлов могут быть:

• 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": "Новый процесс",
            "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": "Исходная таблица_1"
            },
            "guid": "f14f1d6f-2280-4a8b-9514-a41f855d8091",
            "first_column": {
                "column": "FIRST_NAME",
                "table": "Исходная таблица"
            },
            "direction": "DIRECTED"
        },
    ]
}

Папка с настройками

Файл с кодом для работы виджета может иметь любое содержание.

Пример содержимого файла manifest для виджета:

{
  "api_version": 1,
  "name": {
    "en": "Pictures",
    "ru": "Pictures"
  },
  "uuid": "6f9bf5a6-273a-4087-a207-4fb169e02f9b",
  "entry": "index.js",
  "default_size_percentage": {
    "width": 60,
    "height": 20,
    "min_width": 8,
    "min_height": 4
  }
}

где:

• "name" — имя виджета, которое отображается в редакторе дашборда
  • "en": "Pictures" — английская локализация имени пакета
  • "ru": "Pictures" — русская локализация имени пакета
• "uuid": "6f9bf5a6-273a-4087-a207-4fb169e02f9b" — уникальный идентификатор виджета
• entry": "index.js" — имя файла с кодом для работы виджета
• "width": 60 — ширина виджета по умолчанию
• "height": 20 — высота виджета по умолчанию
• "min_width": 8 — минимальная ширина виджета
• "min_height": 4 — минимальная высота виджета

Если это приложение, достаточно указать название файла с кодом в файле manifest. Например:

{
  "entry": "index.js"
}

Требования к загружаемым пакетам

Загружаемые в Маркетплейс или пространство пакеты должны соответствовать следующим требованиям:

• Подготовка пакета не должна выполняться на ПК с macOS
• Файл manifest.json обязательно присутствует в пакете и находится в единственном экземпляре в корне архива
• GUID указан в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx и состоит только из шестнадцатеричных символов
• Версия пакета указана в формате x.x.x
• Пакет соответствует одному из следующих типов: widget, application, workspace
• Файл manifest.json обязательно содержит следующие поля: systems (может быть пустым), author, manifest_version, name, guid, description, categories, type, version
• Названия всех файлов в пакете указаны на английском языке
• Названия иконок, находящихся в папке resources, совпадают с названиями систем, указанных в manifest.json в секции systems. При загрузке пакета без папки resources будет отображаться системная иконка
• Иконки систем с типом файла .png имеют размеры 20x20
• В папке images находятся только файлы .png и .svg
• Путь к изображению указывается без указания папки, т. е. указывается только название изображения. Пример: ![изображение](название_изображения.png)
• В корне архива обязательно присутствует файл или папка с контентом пакета (application.zip/widget.zip/папка workspace)
• Файлы changelog.md, doc.md, папка images не обязательны
• В настоящий момент поддерживаются следующие языки локализаций: ru, en. Manifest-файл может содержать информацию о локализациях, отличных от ru и en, ошибка при загрузке пакета в Маркетплейс в таком случае не возникнет, но в системе такие локализации отображаться не будут
• В manifest-файле в поле dependency указываются GUID и версия пакета, от которого зависит загружаемый пакет. Если указанный пакет отсутствует в Маркетплейсе, то при загрузке текущего пакета возникнет ошибка
• Если в пакете контент находится в папке workspace, то поле manifest_version в файле manifest.json не должно быть равно 1
• В полях min_version_platform и max_version_platform patch-параметр версии указан как "x". Пример: "min_version_platform": "1.24.11.x". Оба поля являются обязательными