Skip to main content

Get Started

This walkthrough starts in an empty folder and ends with a tested plugin installed in Designer. It assumes the CLI is installed and your environment is active. Go to Set Up Environment if not.

Initialize the Workspace

sdk-workspace-init turns the current folder into an SDK workspace.

 mkdir DemoPackage
cd DemoPackage
ayx_plugin_cli sdk-workspace-init

The command prompts for each value. Pass flags to skip the prompts:

 ayx_plugin_cli sdk-workspace-init --package-name DemoPackage --tool-category "Demo Menu" --description "Demo plugins" --author "Jane Developer" --company "Example Co" --backend-language python

Value

Meaning

Package Name

Name of the workspace package and of the YXI it builds.

Tool Category

The Designer tool palette tab where the plugins appear.

Description

Shown to users when they install the YXI.

Author

Who wrote the plugins.

Company

Who owns the plugins.

Back-end Language

python (the only supported value)

The output ends with the workspace location, a note that settings live in ayx_workspace.json, and a "Generating config files" message. The folder now contains ayx_workspace.json, backend/, configuration/, pyproject.toml, and README.md.

Open ayx_workspace.json and check backend_language_settings.python_version against your target Designer release. Change it now if it differs.

Add a Plugin

 ayx_plugin_cli create-ayx-plugin --tool-name MyFirstPlugin --tool-type single-input-single-output

Without flags, the CLI prompts for the plugin name, type, whether it writes data to an external destination, description, version, an optional DCM namespace (press Enter to leave it empty), and whether to skip the configuration panel.

Choose the plugin type that matches the data flow:

Type

Shape

input

No input anchors. Generates data.

output

Input anchor only. Consumes data.

single-input-single-output

One input, one output (default).

multiple-inputs

Several input anchors.

multiple-outputs

Several output anchors.

optional

An input anchor that may be unconnected.

multi-connection-input-anchor

One input anchor that accepts several connections.

Choose carefully. Changing the type later means reworking the anchor handling and the generated configuration.

To skip the configuration panel (and the Node requirement), add --omit-ui:

 ayx_plugin_cli create-ayx-plugin --tool-name MyFirstPlugin --tool-type single-input-single-output --no-writes-output-data --description "Passes data through" --tool-version 1.0 --omit-ui

The command creates the plugin’s Python module, tests, and configuration files, and registers the plugin in ayx_workspace.json. Unless you skip it, it also generates the configuration panel.

Generate or Refresh Scaffolding When Needed

create-ayx-plugin already generates tests and UI. Use these commands to regenerate them later, for example after the template changes:

 ayx_plugin_cli generate-tests --tool-name MyFirstPlugin
ayx_plugin_cli generate-ui --tool-name MyFirstPlugin

Regenerating tests overwrites the generated test file, so keep hand-written tests in separate files.

Implement the Plugin

Open backend/ayx_plugins/my_first_plugin.py. The generated class already passes input to output. Add your logic in the callbacks, for example, on_record_batch. The Example Plugins page shows common patterns.

Update and Run the Tests

The generated tests expect the pass-through behavior. Edit the expected data so it matches what your plugin now does, then run:

 ayx_plugin_cli test

This runs pytest backend. A freshly generated, unmodified plugin passes its own tests, so a failure after your edit points at the edit.

Install into Designer

For fast iteration, build and install in one step:

 ayx_plugin_cli designer-install --install-type user

Restart Designer. The plugin appears in the tool palette under your tool category. Place it on a workflow, connect an input, and run.

To produce a shareable package instead:

 ayx_plugin_cli create-yxi

The YXI is written to build/yxi/. Double-click it, or drag it into Designer, to install. Go to Package and Install.

Change Metadata Later

  • Help link: ayx_plugin_cli update-tool-help --help-url https://example.com/help

  • Anything else in ayx_workspace.json: Edit the file, then run ayx_plugin_cli generate-config-files and restart Designer. To learn which fields are safe to change, go to Workspace and Plugin Structure.

Next Steps