Skip to main content

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

AyxSdkInput

Generates data and writes it to an output anchor. Useful when a workflow starts with external or synthetic data.

Output

AyxSdkOutput

Receives data and finishes without writing output. Useful for plugins that inspect, publish, or send data elsewhere.

Passthrough

AyxSdkPassThrough

Reads input and writes the same data to an output anchor. The simplest example of record flow.

Multiple Input Anchors

AyxSdkMultipleInputAnchors

Coordinates data from more than one input, for example, to compare, merge, or validate two streams.

Optional Input Anchor

AyxSdkOptionalInputAnchor

Runs with or without an incoming connection.

Multiple Output Anchors

AyxSdkMultipleOutputAnchors

Sends records to different outputs based on plugin logic.

Multi-Connection Input, Multiple Outputs

AyxSdkMultiConnectionsMultiOutputAnchor

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

dcm_input.py, dcm_tool.py, dcm_smoke_test.py, dcm_get_write_lock_test.py

Progress Reporting

update_progress_example.py

External Service Calls

external_request_output.py, weather_tool.py

Specialized Data Handling

spatial_tool.py, metadata.py

Arrow Conversion

conversion_passthrough.py, arrowconv.py

Input and Output Edge Cases

giant_input_tool.py, broken_input.py, emptyrow.py

Plugin Identity and Environment

tool_id_test.py, constants_test_tool.py, fips_crypto_test_tool.py

General Reference and Regression

tracer_bullet_plugin_v2.py, danceable_lyrics.py

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

__init__

Stores the provider on the plugin instance and sends a startup message to the Designer log.

on_record_batch

Receives a batch of records from the input anchor, converts it to a DataFrame and back to an Arrow table, and writes it to Output.

on_incoming_connection_complete

Runs when an incoming connection finishes sending data. Useful for logging and cleanup.

on_complete

Runs when the plugin has finished processing. A good place for final messages or cleanup.

What to Take from It

  1. The plugin stores the provider.

  2. The plugin reads records from an input batch.

  3. The plugin writes records to an output anchor.

  4. The plugin can emit informational messages.

Order of Events

  1. Designer starts the plugin.

  2. The plugin is created (__init__).

  3. A record batch arrives (on_record_batch), possibly many times.

  4. The plugin processes the records and writes output.

  5. Each incoming connection completes (on_incoming_connection_complete).

  6. 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

  1. Learn the basic input and output patterns.

  2. Review passthrough and multi-anchor behavior.

  3. Study UI-backed plugins if you need a configuration panel.

  4. 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.