Skip to main content

Package a Tool

Important

The Legacy SDKs use outdated technology that limits your extension opportunities. We've built a new Platform SDK using Python and the latest open-source technology to deliver a vastly improved development experience. Go to Platform SDK to get started!

The YXI file format is an alternative to a .zip archive that displays an installer dialog, providing metainfo to the user about the tool being installed. Use .yxi packaging to package custom tools for distribution to other Alteryx users.

When installed, Designer extracts the YXI contents to one of two paths, based on the selection by the user:

  • To the user path %APPDATA%\Alteryx.

  • For all users on the machine %ALLUSERSPROFILE%\Alteryx.

When installed for all users, the installation excludes files in the root of the YXI archive.

Installation Paths

HTML tools and macros are found in several directories. If Designer detects the same macro installed in multiple places, the order of precedence for resolution is:

User Tools Path

%APPDATA%\Alteryx\Tools

Admin Tools Path

%ALLUSERSPROFILE%\Alteryx\Tools

HTML Plugins Path

<install directory>\bin\HtmlPlugins

Runtime Macro Path

<install directory>\bin\RuntimeData\Macros

If Designer detects the same HTML tool installed in multiple places, the order of precedence is the same.

Paths in Config.xml files can be relative to any of these paths. If you reference the back end macro of an HTML tool as Supporting_Macros\MyMacro.yxmc, Designer attempts to use each of the paths in succession.

Note

Referencing Macro Paths

Designer doesn't attempt to resolve the macro path relative to the HTML tool path. If Supporting_Macros is a subdirectory within the HTML tool, reference the macro path relative to one of the listed paths.

Package Configuration File

Each tool that is distributed via YXI must contain a Config.xml file in the root. This file provides the information needed to ensure the tool is correctly installed into Alteryx Designer. The file contains the metainfo for...

  • The Installer Icon

  • The Installer Name

  • The Category the Installed Tools Appear In

  • The Installer Version

  • The Tool's Author

  • The Description of the Installer Contents

Note

Image Pixel Limitation

Icons have a 171 x 171 pixel size limit. If your image is not rendering on the canvas, try adding a transparent border around the icon.

Example Config.xml

<?xml version="1.0"?>
<Configuration>
        <Properties>
                <MetaInfo>
                        <Icon>MyNiftyPlugin\MyNiftyPlugin.png</Icon>
                        <Name>My Nifty Plugin</Name>
                        <CategoryName>Parse</CategoryName>
                        <ToolVersion>1.0.0</ToolVersion>
                        <Author>Alteryx</Author>
                        <Description>This is my Nifty plugin, which appears in Parse.</Description>
                </MetaInfo>
        </Properties>
</Configuration>

Package Creation

  1. Create a .zip file with this folder structure:

    • Tool folder: A folder that contains the custom tool assets. Include one folder per tool being installed. See Getting Started with Developer for information about the contained assets.

      • Tool Configuration .xml File

      • Tool Icon .png File

      • Tool Engine File or Supporting_Macros Folder

      • Tool .html GUI File

      • Optional: You can separate JavaScript from your .html file into a separate .js file.

    • Package Config.xml file: A file at the root of the .yxi used to configure the installer dialog.

    • Package icon.png file. This can also be the icon inside the tool folder.

  2. Rename the .zip file to have a .yxi extension.

Note

Package Multiple Tools in Single YXI

You can package multiple tools in a single YXI. To do so, place multiple tool folders at the same level as the Config.xml and icon.png files. The file structure for multiple tools should look like this:

  • Tool Folder A

  • Tool Folder B

  • Config.xml

  • icon.png

Build Your Own Tool Checklist

In this section: