Skip to main content

End-to-End Platform SDK Quickstart

This tutorial walks you through the smallest complete path for building a custom Alteryx Designer plugin with the Platform SDK. The plugin is written in Python and has only a back end. It has one input, one output, and no configuration panel. When you finish, you will have a working plugin installed in Designer and have confirmed that it produces the expected output records.

What You Build

You build a plugin called Uppercase Text. It reads one text column named Value from its input and writes the same records back out with Value converted to uppercase. The plugin has one input anchor (Input), one output anchor (Output), no configuration panel, and no saved connections.

Before You Start

You need these items:

  • Windows 11, 64-bit. Designer and the AYX Plugin CLI run only on Windows.

  • Alteryx Designer: Designer version for this tutorial: 2026.3. Install Designer through the Alteryx One App.

  • Python 3.13 on your development machine. Use a separate Python installation for development. The Python that ships with Designer is a separate runtime, and you don’t use it to create your development environment.

The embedded Python that ships with Designer and the two ayx packages used by the plugin are intentionally not listed as separate development prerequisites. Designer supplies the runtime, and Step 2 installs the pinned development dependencies into the dedicated virtual environment.

You don’t need Node.js or npm for this tutorial. The plugin has no configuration panel, so you skip the user interface files.

All commands in this tutorial are PowerShell commands. Run each one from the folder named at the start of its section.

Create and Activate Development Environment

Work in a new, empty folder for your workspace, for example, C:\dev\uppercase-text.

# One-time: install uv if it is not already installed
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv python install 3.13

mkdir C:\dev\uppercase-text
cd C:\dev\uppercase-text
uv venv --python 3.13 --seed .venv
.\.venv\Scripts\Activate.ps1

The expected result is that your prompt starts with (.venv), and python --version reports Python 3.13.

Install SDK and CLI

Run these steps from C:\dev\uppercase-text with .venv active.

python -m pip install --upgrade pip
pip install ayx_plugin_cli==1.4.0 ayx_python_sdk==2.6.1

The expected result is that ayx_plugin_cli version prints 1.4.0. If Windows doesn’t recognize the command, confirm that the virtual environment is active and reinstall the pinned CLI package.

Create the Workspace

An SDK workspace is the project folder that holds one or more plugins. It also holds the shared metadata and build files that the CLI needs to package and install them.

Run this step from C:\dev\uppercase-text. Create the workspace:

 ayx_plugin_cli sdk-workspace-init `
  --package-name UppercaseTextPackage `
  --tool-category "Quickstart Tools" `
  --description "Quickstart backend-only tool" `
  --author "Your Name" `
  --company "Your Company" `
  --backend-language python

The expected result is that the command finishes without errors. The workspace root now includes these items:

 ayx_workspace.json
backend/
  ayx_plugins/__init__.py
  requirements-local.txt
  requirements-thirdparty.txt
  setup.py
configuration/
DcmSchemas/

ayx_workspace.json holds the workspace source metadata. It records the package name, author, company, category, and the list of plugins. The CLI reads and writes this file, so you don’t normally edit it.

Run every remaining CLI command in this tutorial from the workspace root, which is the folder that contains ayx_workspace.json.

Create the Plugin

Run this step from C:\dev\uppercase-text. Create the plugin:

 ayx_plugin_cli create-ayx-plugin `
  --tool-name UppercaseText `
  --tool-type single-input-single-output `
  --no-writes-output-data `
  --description "Uppercase values in the Value field." `
  --tool-version 1.0 `
  --dcm-namespace= `
  --omit-ui

The expected result is that the CLI reports that it created UppercaseText, and ayx_workspace.json now lists the plugin. The workspace gains these files:

 backend/ayx_plugins/uppercase_text.py
backend/ayx_plugins/__init__.py         (updated with the new import)
configuration/UppercaseText_1_0/
  UppercaseText_1_0Config.xml
  manifest.json
  icon.png

The options in the above command do the following:

  • --tool-type single-input-single-output generates a plugin with one input anchor (Input) and one output anchor (Output). This is the smallest complete data flow.

  • --omit-ui skips the React configuration panel. The plugin stays backend-only, and you don’t need Node.js or npm.

  • --no-writes-output-data marks the plugin as one that doesn’t write to an external destination, such as a file or a database. Designer skips plugins that write to an external destination when a user selects Disable All Tools that Write Output in Designer's Runtime settings.

Generated Workspace Structure

Path

What It Is

Source or Generated?

ayx_workspace.json

Workspace metadata: package, author, and plugin list.

Do not edit. The CLI maintains it.

backend/ayx_plugins/uppercase_text.py

The Python class for your plugin.

You edit this. This is the generated starter code.

backend/ayx_plugins/__init__.py

Imports every plugin class in the workspace.

Do not edit. The CLI maintains it.

backend/requirements-thirdparty.txt

Third-party packages that your plugin needs at runtime.

Edit this if your plugin needs extra packages.

backend/requirements-local.txt

Local and editable package requirements.

Rarely edited for a simple plugin. This is generated.

backend/setup.py

Packaging metadata for the back-end package.

Do not edit. This is generated.

configuration/UppercaseText_1_0/UppercaseText_1_0Config.xml

Tells Designer about the plugin’s anchors, icon, and entry point.

Do not edit. This is generated. Instead, regenerate it with generate-config-files.

configuration/UppercaseText_1_0/icon.png

The icon in the Tool Palette.

Replace the placeholder with your own icon later.

In this tutorial, you change only backend/ayx_plugins/uppercase_text.py.

Implement the Transformation

Run these steps from C:\dev\uppercase-text.

  1. Open backend\ayx_plugins\uppercase_text.py.

    The generated on_record_batch method passes the incoming batch straight through:

     def on_record_batch(self, batch: "Table", anchor: namedtuple) -> None:
        self.provider.write_to_anchor("Output", batch)
  2. Replace the contents of the file with this code. It converts the Value column to uppercase with Arrow compute functions before it writes the result.

     """Uppercase Text tool."""
    from collections import namedtuple
    
    from ayx_python_sdk.core import PluginV2
    from ayx_python_sdk.providers.amp_provider.amp_provider_v2 import AMPProviderV2
    
    import pyarrow as pa
    import pyarrow.compute as pc
    from pyarrow import Table
    
    
    class UppercaseText(PluginV2):
        """Concrete implementation of a Plugin."""
    
        def __init__(self, provider: AMPProviderV2) -> None:
            """Construct a plugin."""
            self.name = "UppercaseText"
            self.provider = provider
            self.provider.io.info(f"{self.name} tool started")
    
        def on_incoming_connection_complete(self, anchor: namedtuple) -> None:
            """Call when an incoming connection finishes sending data."""
            self.provider.io.info(
                f"Received complete update from {anchor.name}:{anchor.connection}."
            )
    
        def on_record_batch(self, batch: "Table", anchor: namedtuple) -> None:
            """Uppercase the Value column and write the result to Output."""
            upper_value = pc.utf8_upper(batch.column("Value"))
            result = batch.set_column(
                batch.schema.get_field_index("Value"), "Value", upper_value
            )
            self.provider.write_to_anchor("Output", result)
    
        def on_complete(self) -> None:
            """Clean up any plugin resources."""
            self.provider.io.info(f"{self.name} tool done.")
    

The Input anchor expects a table with at least a string column named Value. The Output anchor returns the same table with Value in uppercase. For example, this input produces this output:

Input Value

Output Value

alteryx

ALTERYX

designer

DESIGNER

Test the Plugin Locally

Run these steps from C:\dev\uppercase-text.

  1. Generate a test for the plugin.

    ayx_plugin_cli generate-tests --tool-name UppercaseText

    The CLI creates or refreshes backend/tests/test_uppercase_text.py and its supporting fixtures. The test uses the SDK’s SdkToolTestService and pytest, the same combination that the CLI’s test command runs.

  2. Update the test for the Value column.

    The generated test uses a default two-column numeric schema (col1: int64 and col2: float64) and checks that the output matches the input. In backend/tests/test_uppercase_text.py, change the fixture schema and data to a single Value string column, and change the assertion to expect uppercase output. For example:

     from ayx_python_sdk.core import Anchor
    from ayx_python_sdk.core.testing import BatchTuple, SdkToolTestService
    
    from backend.ayx_plugins.uppercase_text import UppercaseText
    
    import pyarrow as pa
    from pyarrow import RecordBatch
    
    import pytest
    
    
    TEST_SCHEMA = pa.schema([("Value", pa.string())])
    
    
    @pytest.fixture
    def small_batches():
        return BatchTuple(
            input_data=RecordBatch.from_arrays([["alteryx", "designer"]], schema=TEST_SCHEMA),
            expected_output_data=RecordBatch.from_arrays([["ALTERYX", "DESIGNER"]], schema=TEST_SCHEMA),
        )
    
    
    @pytest.fixture
    def uppercase_text():
        return SdkToolTestService(
            plugin_class=UppercaseText,
            config_mock="<Configuration/>",
            input_anchor_config={"Input": False},
            output_anchor_config={"Output": False},
        )
    
    
    def test_init(uppercase_text):
        assert uppercase_text.plugin is not None
    
    
    def test_on_record_batch(uppercase_text, small_batches):
        input_batch = small_batches.input_data
        expected_output = small_batches.expected_output_data
        uppercase_text.run_on_record_batch(input_batch, Anchor("Input", "1"))
        assert uppercase_text.data_streams["Output"] == [expected_output]
    

    This example simplifies the fixture wiring that generate-tests produces. Keep the fixture style from your generated file. Change only the schema, the sample data, and the output assertion.

  3. Run the tests.

    ayx_plugin_cli test

    The command runs pytest backend and prints the results.

pytest reports that the UppercaseText tests pass, for example:

 backend/tests/test_uppercase_text.py ...                               [100%]

ayx_plugin_cli test doesn’t return pytest’s failing exit status to the shell. In scripts or CI, run pytest backend directly.

If the run fails with a KeyError or a schema mismatch, a fixture or an assertion probably still uses the default col1 and col2 schema. Confirm that every fixture and assertion in the test file uses Value.

<title>Package the Plugin</title>

Run this step from C:\dev\uppercase-text.

ayx_plugin_cli create-yxi

The expected result is that the CLI reports a successful build, and the package appears at:

build\yxi\UppercaseTextPackage.yxi

The file name matches the name field in ayx_workspace.json. That field defaults to the --package-name value that you set when you created the workspace (Step 3).

<title>Install the Plugin in Designer</title>

Run this step from C:\dev\uppercase-text.

ayx_plugin_cli designer-install --dev --install-type user

The expected result is that the CLI prints a success message. If this is the first time that you install a plugin from this workspace, restart Designer. Designer scans its Tools folders for new tools only at startup.

The options in this command do the following:

  • --dev installs the workspace in development mode. This is the recommended workflow. Designer uses the workspace’s development files, so you can test changes without treating each change as a new packaged release. Use it for fast local iteration.

  • --install-type user installs the plugin for the current user. Use --install-type admin only when an administrator needs to install the plugin for all users.

The Designer Tools directory can vary by release, so rely on the success message and don’t assume a fixed path.

Install the Packaged Plugin Instead

To test the artifact that you would distribute to other users, omit --dev:

ayx_plugin_cli designer-install --install-type user

Without --dev, the CLI installs the YXI package that ayx_plugin_cli create-yxi produced. After you change the source, run create-yxi again, and then run designer-install again to install the updated package.

Choose --dev for rapid local iteration, omit it to validate the packaged installation. In either case, the --install-type user and --install-type admin options control whether the install is scoped to your user account or to all users, and Designer may need to be restarted before a newly installed plugin appears.

Test the Plugin in Designer

Passing pytest tests doesn’t guarantee that the plugin works in Designer. The ayx_plugin_cli test command doesn’t exercise packaging, installation, or the Designer runtime, so always run this test in Designer.

  1. Open Alteryx Designer.

  2. In the Tool Palette, open the Quickstart Tools category and find Uppercase Text. The category is the value that you set with --tool-category when you created the workspace (Step 3).

  3. Add a Text Input tool to the canvas. Add one column named Value with the type String, and enter two rows: alteryx and designer.

  4. Connect the output of Text Input to Uppercase Text.

  5. Connect the output of Uppercase Text to a Browse tool.

  6. Go to Workflow - Configuration > Runtime, and select Use AMP Engine.

  7. Run the workflow.

The expected result is that the Browse tool shows two rows. Value is ALTERYX in the first row and DESIGNER in the second.

Troubleshooting

A Command Fails with a Workspace Error

sdk-workspace-init or create-ayx-plugin fails. Confirm that you run the command from the folder that contains, or should contain, ayx_workspace.json. Most CLI commands check that this file exists before they do anything else.

create-ayx-plugin Fails with "Duplicate tool names are prohibited"

A plugin with that class name already exists in ayx_workspace.json. Choose a different --tool-name. If the existing entry is from a false start, remove it.

generate-ui or create-ayx-plugin Reports a Problem with Node or npm

UI generation requires Node.js and npm. This tutorial avoids that requirement with --omit-ui. If you see this error, confirm that you passed --omit-ui when you created the plugin.

pytest Fails with KeyError: ’Value’ or a Schema Error

The generated test fixtures default to a col1 and col2 numeric schema. Confirm that every fixture and assertion in backend/tests/test_uppercase_text.py uses the single Value string column (Step 6).

create-yxi or designer-install Fails with an Empty Tool Set Error

The workspace has no registered plugins, or ayx_workspace.json doesn’t list UppercaseText. Run the create-the-plugin step again (Step 4), and confirm that the CLI created the plugin before you package it.

The Plugin Doesn’t Appear in the Designer Tool Palette

Restart Designer. Designer picks up newly installed plugins, and plugins whose ayx_workspace.json changed, only at startup.

The Workflow Runs but Value Isn’t in Uppercase, or the Plugin Reports an Error

Confirm that the column in the Text Input tool is named Value, with that exact spelling and capitalization, and that its type is String. The on_record_batch method looks up the column by that name.