How to create and share an Alteryx Tool Installer (a .yxi file)

Alteryx introduced a new file type in version 10.5 – the .yxi file. (See the announcement of this from Ben Gomez, Alteryx’s Senior Product Manager, here on the Alteryx community.)So why should you be excited about this? Well, because it makes sharing custom tools or macros incredibly easy. You may have come across a .yxi file already if you’ve installed the google sheets connector tools, or the text analytics tool – both are installed with the help  of a yxi file.In a nutshell, a yxi file is simply a (zipped) package of a tool and all its underlying components. When it is opened with Alteryx, all these components are saved to the correct location on your machine. This enables you to use the tool just like any other tool from the tool bar, hence a yxi file is an ‘installer’.Currently, macros with supporting files are shared to the Alteryx gallery in the form of a yxzp. A yxzp is also essentially a zip file that contains the macro and all the supporting files (assets). When someone wants to download and install it, they must ensure that they place all the supporting files into their macro repository, such that the macro correctly references its assets. This can be somewhat cumbersome; whereas a yxi installer makes the installation of the macro/tool and its supporting files seamless.If you want some more detail, read on. In this blog post I will be addressing:

• What a .yxi file actually is and what it contains
• What alteryx does when you open a .yxi file
• How you can make your own
• How to share your tool and its installer

So firstly, what is a yxi file, and what’s in it?

It is a form of compressed or zipped file. The .yxi extension simply lets Alteryx know that it should install the contents. If you change the extension to .zip, you can unpack the file and see what’s inside. Sticking with the google sheets and the text analytics tools we see the following:The best way to find out what something is doing is to tear it open and see how it works. Taking both our google sheets and microsoft text analytics tools as examples, we can look for similarities in the structure and contents of the unpackaged files. So let's have a look:There are 3 clear levels in  the folder structure. At the top  level, we have a config.xml file, an icon png and a folder for each tool to be installed. In each tool's folder, we have another tool-specific config.xml, another icon, and then the html and javascript files that make up the tool. Finally, we then have a folder of supporting macros.

Great, but what does Alteryx do with it?

So here's the bit which saves us as users tons of effort. When you open a .yxi file in Alteryx, it will give you a nice pop-up telling you some information about the tool or tools you are about to install.What it does under the hood, is place the contents of the file into a location that means the tools (and all the bits required to run them) are available from your tool bar, just like any of the tools installed with Alteryx. You can find this location at: C:\\Users\\user\\AppData\\Roaming\\Alteryx\\ToolsNote that you'll need to show hidden folders as AppData is a hidden folder.In  here you will find the folders for any tool you have installed using a yxi file - you can see I've installed a few. Opening up any of those folders, you'll find exactly what was in the .yxi package.Now you get a real sense of what exactly all the fuss is about. You can build a tool as complex as you like, whether it's a macro with lots of supporting macros, or a tool built using custom code with the Alteryx Software Developer Kit. When you then share your tool, everything is packaged up and installed seamlessly, without your user having to see the pieces behind it or risk partially installing them somehow.

Cool! So how do I make my own?

This is where it gets fun. We need to strip the yxi back to its most essential pieces and reconstruct it with our own macro. In my case, I wanted to create an installer for a text translation macro I had built, that relied on a nested batch macro to work properly. In the interest of keeping things simple, I won't go into detail with a more complex example using html/js files - take apart the google sheets tools for yourself if you are interested! The general 'take it apart to see how it works' approach is applied here.

1. Create the folder structure and place your essential files in there

2. Create or edit your config xml  file

I copied mine from an existing .yxi and edited the necessary parts to suit my use case. You can copy the text here and do the same, just make sure you save it as 'Config.xml'

<?xml version='1.0'?><AlteryxJavaScriptPlugin><Properties><MetaInfo><Name>Cognitive Services Text Translation</Name><Description><![CDATA[Use the Microsoft Cognitive Services Text Translator API to easily batch translate text from any, and to any, of over 60 supported languages.]]></Description><ToolVersion>1</ToolVersion><CategoryName>Connectors</CategoryName><Author>Peter GB - The Information Lab</Author><Icon>translate_icon.png</Icon></MetaInfo></Properties></AlteryxJavaScriptPlugin>

We can see exactly how the Config.xml relates to the pop up Alteryx gives you when opening the .yxi, so be sure to edit each part to suit your needs.

3. Set your macro metadata in the workflow configuration pane, on the Meta Info tab

This affects where the tool shows up in the tool bar, and what information  is displayed on the hover.

4. Set your macro's custom icon from in the interface designer

5. Ensure the filepaths to any supporting macros are relative file paths

In my example my main macro uses another macro that handles the API calls. I opened the main macro .yxmc in a text editor, found the reference to my supporting macro, and edited the path such that it is relative and points to the Supporting_Macros folder in my soon-to-be yxi package.

6. Compress to a zipped file, and change the extension from .zip to .yxi

Now make your zip file. Important- Do not compress the folder containing your folder structure, as this will create an extra folder in the package - Alteryx will not be able to find the Config.xml in this case. Instead, highlight everything you need to be in the top layer of the package as in the gif below.Don't forget to change the .zip to a .yxi and finally you have your installer package.Test it out with alteryx and check your installer pop-up appears with the correct information, verify the tool works correctly, and you can even check in the AppData folder to see that all the components were installed correctly.

Great! - How do I share  it?

Alteryx gallery currently doesn't really support sharing of yxi files, so you make a dummy workflow (so you have something to share on the gallery), and self-host the yxi. The user then gets a download link.

• Self host your .yxi file somewhere (could simply be a public dropbox or google drive folder, or your own website)
• Build a dummy workflow so you have something to upload to the Alteryx Gallery (this serves only to provide the download link to your .yxi)
• Make sure  your workflow metadata is filled out properly, as this will be displayed on the gallery like so:

That's it!

One final note:

If you share workflows that use a tool that was installed via a .yxi file, the custom tools will not be packaged up with the workflow (when you export packaged workflow to a yxzp file). This is because they are now 'installed' into your local installation  of the Alteryx software. Anyone you are sharing the workflow with will have to use the yxi to install the custom tools themselves - so just be aware of that :)This was a manual way of creating the file in order to learn what exactly it is and what it does through trial and error, with some pointers from my colleagues!  Alteryx wizard James Dunkerly has actually automated the process in a powershell script in case you'd like to use that,  you can find it on his blog here.