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 pythonThe 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.pngThe options in the above command do the following:
--tool-type single-input-single-outputgenerates a plugin with one input anchor (Input) and one output anchor (Output). This is the smallest complete data flow.--omit-uiskips the React configuration panel. The plugin stays backend-only, and you don’t need Node.js or npm.--no-writes-output-datamarks 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? |
|---|---|---|
| Workspace metadata: package, author, and plugin list. | Do not edit. The CLI maintains it. |
| The Python class for your plugin. | You edit this. This is the generated starter code. |
| Imports every plugin class in the workspace. | Do not edit. The CLI maintains it. |
| Third-party packages that your plugin needs at runtime. | Edit this if your plugin needs extra packages. |
| Local and editable package requirements. | Rarely edited for a simple plugin. This is generated. |
| Packaging metadata for the back-end package. | Do not edit. This is generated. |
| Tells Designer about the plugin’s anchors, icon, and entry point. | Do not edit. This is generated. Instead, regenerate it with |
| 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.
Open
backend\ayx_plugins\uppercase_text.py.The generated
on_record_batchmethod passes the incoming batch straight through:def on_record_batch(self, batch: "Table", anchor: namedtuple) -> None: self.provider.write_to_anchor("Output", batch)Replace the contents of the file with this code. It converts the
Valuecolumn 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.
Generate a test for the plugin.
ayx_plugin_cli generate-tests --tool-name UppercaseText
The CLI creates or refreshes
backend/tests/test_uppercase_text.pyand its supporting fixtures. The test uses the SDK’sSdkToolTestServiceandpytest, the same combination that the CLI’stestcommand runs.Update the test for the
Valuecolumn.The generated test uses a default two-column numeric schema (
col1: int64andcol2: float64) and checks that the output matches the input. Inbackend/tests/test_uppercase_text.py, change the fixture schema and data to a singleValuestring 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-testsproduces. Keep the fixture style from your generated file. Change only the schema, the sample data, and the output assertion.Run the tests.
ayx_plugin_cli testThe command runs
pytest backendand 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.
Run this step from C:\dev\uppercase-text.
ayx_plugin_cli create-yxiThe 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).
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:
--devinstalls 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 userinstalls the plugin for the current user. Use--install-type adminonly 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.
Open Alteryx Designer.
In the Tool Palette, open the Quickstart Tools category and find Uppercase Text. The category is the value that you set with
--tool-categorywhen you created the workspace (Step 3).Add a Text Input tool to the canvas. Add one column named
Valuewith the type String, and enter two rows:alteryxanddesigner.Connect the output of Text Input to Uppercase Text.
Connect the output of Uppercase Text to a Browse tool.
Go to Workflow - Configuration > Runtime, and select Use AMP Engine.
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.