Example Plugins
The SDK includes example plugins that show common patterns and some specialized workflows. They are useful as learning material and as starting points for new plugins.
If SDK concepts are new, start with the examples. They show how the plugin class, anchors, and generated workspace files fit together.
Why Examples Matter
Examples show:
How the plugin class is written.
How anchors are handled.
How records are written to output.
How progress updates are sent.
How UI and backend code work together.
They also show what a real plugin looks like once the scaffold has been generated and the author has started editing.
Starter Examples
The SDK package ships one example per plugin type under ayx_python_sdk/examples/. Each matches what create-ayx-plugin generates for the corresponding --tool-type.
Pattern | Example Folder | What it Demonstrates |
|---|---|---|
Input | | Generates data and writes it to an output anchor. Useful when a workflow starts with external or synthetic data. |
Output | | Receives data and finishes without writing output. Useful for plugins that inspect, publish, or send data elsewhere. |
Passthrough | | Reads input and writes the same data to an output anchor. The simplest example of record flow. |
Multiple Input Anchors | | Coordinates data from more than one input, for example, to compare, merge, or validate two streams. |
Optional Input Anchor | | Runs with or without an incoming connection. |
Multiple Output Anchors | | Sends records to different outputs based on plugin logic. |
Multi-Connection Input, Multiple Outputs | | Handles several connections on one anchor, in a defined order. |
Use only the folders under examples/. These are the best starting point for new authors.
Additional Backend Examples
The SDK repository also has example plugins under ExampleTools/backend for more specialized behavior. They live in the repository, not in the installed SDK package.
Topic | Examples |
|---|---|
DCM-Aware Workflows | |
Progress Reporting | |
External Service Calls | |
Specialized Data Handling | |
Arrow Conversion | |
Input and Output Edge Cases | |
Plugin Identity and Environment | |
General Reference and Regression | |
Some of these are regression or edge-case fixtures rather than recommended designs, so read them for the behavior they exercise rather than as templates.
Walkthrough: A Simple Pass-Through Plugin
conversion_passthrough.py is a good first tutorial. It is small and shows the main parts of a basic plugin.
What It Does
The plugin reads a batch from its input anchor and converts it to a pandas DataFrame. It then writes the data to the Output anchor as an Arrow table. It does not change the data. It shows how to receive a batch and send it onward.
Structure
class ConversionPassthrough(PluginV2):
def __init__(self, provider):
self.provider = provider
self.provider.io.info("Pass through tool started")
def on_record_batch(self, batch, anchor):
df = batch.to_pandas()
batch_to_send = pa.Table.from_pandas(df=df)
self.provider.write_to_anchor("Output", batch_to_send)
def on_incoming_connection_complete(self, anchor):
self.provider.io.info(f"Connection {anchor.connection} on Anchor {anchor.name}")
def on_complete(self):
self.provider.io.info("Pass through tool done")Method | What It Does |
|---|---|
| Stores the provider on the plugin instance and sends a startup message to the Designer log. |
| Receives a batch of records from the input anchor, converts it to a DataFrame and back to an Arrow table, and writes it to |
| Runs when an incoming connection finishes sending data. Useful for logging and cleanup. |
| Runs when the plugin has finished processing. A good place for final messages or cleanup. |
What to Take from It
The plugin stores the provider.
The plugin reads records from an input batch.
The plugin writes records to an output anchor.
The plugin can emit informational messages.
Order of Events
Designer starts the plugin.
The plugin is created (
__init__).A record batch arrives (
on_record_batch), possibly many times.The plugin processes the records and writes output.
Each incoming connection completes (
on_incoming_connection_complete).The plugin completes (
on_complete).
This sequence is the foundation for most SDK plugins.
How to Use the Examples
Focus on the pattern an example demonstrates rather than its file name:
Use input and passthrough examples to learn basic record flow.
Use progress examples to learn how to report status to Designer.
Use DCM examples to see how connection-aware plugins are structured.
Use edge-case examples to understand unusual input or output behavior.
Suggested Learning Path
Learn the basic input and output patterns.
Review passthrough and multi-anchor behavior.
Study UI-backed plugins if you need a configuration panel.
Explore the advanced examples when you need a specific capability such as DCM or external requests.
To create your own plugin from a matching template, go to Get Started.