Skip to main content

Workspace and Plugin Structure

This page explains how the CLI organizes a project: what a workspace and a plugin are, what the generated folders contain, and what ayx_workspace.json holds.

Workspace and Plugin

  • A workspace is the project root created by ayx_plugin_cli sdk-workspace-init. It owns the metadata file ayx_workspace.json, the shared build configuration, and the list of plugins.

  • A plugin is one Designer tool created inside the workspace with create-ayx-plugin. It has a Python class, generated configuration files, generated tests, and optionally a configuration panel project.

  • One workspace builds one distributable package (one YXI). That package can hold one plugin or several.

Situation

Structure

One standalone plugin.

One workspace, one plugin.

Several plugins released together with shared metadata.

One workspace, several plugins.

Plugins with different release schedules or owners.

Separate workspaces.

Generated Layout

After sdk-workspace-init and one create-ayx-plugin --tool-name MyFirstPlugin:

 MyWorkspace/
  ayx_workspace.json
  pyproject.toml
  README.md
  .gitignore
  backend/
    requirements-local.txt
    requirements-thirdparty.txt
    setup.py
    ayx_plugins/
      __init__.py
      my_first_plugin.py
    tests/
      README.md
      test_my_first_plugin.py
  configuration/
    Config.xml
    default_package_icon.png
    MyFirstPlugin_1_0/
      icon.png
      manifest.json
      MyFirstPlugin_1_0Config.xml
  ui/                         (only when a configuration panel was generated)
    MyFirstPlugin/
  DcmSchemas/                 (used by plugins that register DCM schemas)
  .ayx_cli.cache/             (build cache, created by CLI commands)
  build/yxi/                  (created by create-yxi)

Initialization also creates a few additional empty folders for optional features. Leave them in place.

Path

Role

Edit by hand?

ayx_workspace.json

Workspace and plugin metadata.

Rarely. Refer to Editing the Workspace File.

backend/ayx_plugins/<snake_name>.py

The plugin’s Python class.

Yes. This is where behavior lives.

backend/ayx_plugins/__init__.py

Imports each plugin class so the runtime can find it.

Rarely. create-ayx-plugin maintains it.

backend/tests/test_<snake_name>.py

Generated pytest tests.

Yes. They need editing to match real behavior.

backend/requirements-thirdparty.txt

Third-party Python dependencies bundled into the package.

Yes. Add packages the plugin imports.

backend/requirements-local.txt

Local Python packages bundled into the package.

Yes, when the plugin depends on local code.

backend/setup.py

Packaging boilerplate for the backend.

Rarely

configuration/Config.xml

Package-level Designer configuration.

No. It is regenerated.

configuration/<Class>_<version>/

Per-plugin icon, manifest, and configuration XML.

No, except replacing icon.png

ui/<Class>/

The plugin’s configuration panel project.

Yes

pyproject.toml

pytest settings (testpaths = ["backend"])

Rarely

Plugin Naming

You can enter a plugin name with spaces, such as "A Test Plugin". The CLI derives the other names from it:

Item

Example for A Test Plugin

Class, UI, and Configuration Name

ATestPlugin

Python File

a_test_plugin.py

Configuration Folder

ATestPlugin_1_0 (class name plus version, with dots replaced by underscores)

A plugin name must start with a letter and contain only letters, digits, and spaces. Names that would collide with an existing plugin’s class or file are rejected.

ayx_workspace.json

ayx_workspace.json is the source of truth for the workspace. It describes the set of plugins that will be packaged and distributed, and the CLI reads it to generate the top-level Config.xml, each plugin’s configuration XML and manifest, and the YXI. It is created when you initialize the workspace, and the CLI updates it as you add plugins so it stays in sync with the folder structure.

Package-Level Fields

Field

Meaning

name

Package name. Also the YXI file name.

tool_category

Default Designer tool palette tab for every plugin.

package_icon_path

Package icon (.png), relative to the workspace.

author, company, copyright, description

Package metadata.

ayx_cli_version

CLI version that created the workspace.

backend_language

python

backend_language_settings.python_version

Python version for the packaged plugins. Must match the target Designer release.

backend_language_settings.requirements_local_path, requirements_thirdparty_path

Dependency files bundled into the package.

tool_version

Default plugin version.

Per-Plugin Fields (under tools.<Name>)

Field

Meaning

backend.tool_module, backend.tool_class_name

Where the class lives and its name. Drives generated file and folder names.

configuration.long_name

Display name in Designer.

configuration.description

Plugin description.

configuration.version

Plugin version. Part of the configuration/<Class>_<version>/ folder name.

configuration.search_tags

Tool palette search tags.

configuration.help_url

Help link opened from Designer. Defaults to https://help.alteryx.com/developer-help.

configuration.icon_path

Plugin icon, relative to the workspace.

configuration.input_anchors, configuration.output_anchors

Anchor names, labels, allow_multiple, optional.

configuration.writes_output_data

Marks plugins that write to an external destination, so Designer’s option to Disable All Tools that Write Output in Workflow Configuration Runtime settings can disable them.

configuration.dcm_namespace

Data Connection Manager (DCM) schema namespace. Empty when the plugin does not use DCM.

configuration.tool_category

Per-plugin palette override, null inherits the package value

Sample File

An illustrative file for a workspace with one plugin. Your values will differ.

 {
    "name": "TestTools",
    "tool_category": "Test Tools",
    "package_icon_path": "configuration\\default_package_icon.png",
    "author": "John Doe",
    "company": "Alteryx, Inc",
    "copyright": "2026",
    "description": "A sample Alteryx workspace",
    "ayx_cli_version": "1.4.0",
    "backend_language": "python",
    "backend_language_settings": {
        "python_version": "3.13",
        "requirements_local_path": "backend\\requirements-local.txt",
        "requirements_thirdparty_path": "backend\\requirements-thirdparty.txt"
    },
    "tools": {
        "TestPlugin": {
            "backend": {
                "tool_module": "ayx_plugins",
                "tool_class_name": "TestPlugin"
            },
            "ui": {},
            "configuration": {
                "long_name": "Test Plugin",
                "description": "",
                "version": "1.0",
                "search_tags": [],
                "help_url": "https://help.alteryx.com/developer-help",
                "icon_path": "configuration\\TestPlugin_1_0\\icon.png",
                "writes_output_data": false,
                "tool_category": null,
                "input_anchors": {
                    "Input": { "label": "", "allow_multiple": false, "optional": false }
                },
                "output_anchors": {
                    "Output": { "label": "", "allow_multiple": false, "optional": false }
                }
            }
        }
    },
    "tool_version": "1.0"
}

Editing the Workspace File

The CLI manages this file, so prefer CLI commands such as create-ayx-plugin and update-tool-help. If you edit it by hand:

  1. Keep to metadata such as descriptions, search tags, help URL, and categories. Editing names, versions, or anchors renames generated folders and breaks references inside them. Recreate the plugin instead.

  2. Run ayx_plugin_cli generate-config-files afterward.

  3. Restart Designer.

Hand edits can cause unpredictable results, so treat them as an advanced option.

Generated Configuration Files

  • configuration/Config.xml describes package metadata at the top level.

  • Each plugin’s <Class>_<version>Config.xml is used by the plugin to get and set anchors.

  • Each plugin’s manifest.json describes the plugin to Designer.

Do not edit these. generate-config-files rebuilds all of them from ayx_workspace.json, and create-ayx-plugin refreshes them when it adds a plugin. update-tool-help changes only ayx_workspace.json, so run generate-config-files after it.

Next Steps

  • For information on every CLI command, with its flags, defaults, and behavior, go to Command Reference.

  • To learn how to turn a workspace into something Designer can run, go to Package and Install.