Community Spring Cleaning week is here! Join your fellow Maveryx in digging through your old posts and marking comments on them as solved. Learn more here!

Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
IraWatt
17 - Castor
17 - Castor

Whether you are sharing Macros or Tools with your friends and colleagues or building tool kits for the Community Gallery, the Alteryx Tool Installer file is the perfect way to package them.

 

YXI Gif.gif

Source: GIPHY

 

Topics Covered

  • What are yxi files
  • Creating a yxi file from a macro/macros
  • Creating a yxi automatically using the SKD CLI

Prerequisites

 

Understanding how to first create a Tool is useful before learning how to create a Tool Installer. Check out the Alteryx Communities interactive videos for a quick and straightforward guide on how to build Macros: Alteryx Macros. Likewise, if you want to code, check out Alteryx SDK QuickStart Guide for an introductory course on the Alteryx SDK.

 

What are .yxi files?

 

Opening YXI.gif

 

Alteryx Tool Installer files come with the .yxi file extension. It allows for the simple installation of one or many macros and/or SDK-based tools (and dependencies) in one file. The .yxi file type, developed by Alteryx, when opened in Designer, prompts the user with an installer pop-up containing both the tool’s metadata, including name, category, version, author, picture, etc., as well as the option to install either locally or to all users on a machine.

 

For local user installs, the tool will be added to the \Users\USERNAME\AppData\Roaming\Alteryx\Tools\ directory.  

 

For all user installs, the tool will be added to the \ProgramData\Alteryx\Tools directory. 

 

Creating a yxi file from a macro/macros

 

It is very straightforward to create a yxi file for a macro. The first step is to create a config file that contains all the metadata about your tool installer file.

 

The config file is structured in an XML format; an example structure is shown below:

 

<?xml version=”1.0” encoding=”UTF-8”?>

<Configuration>

  <Properties>

    <MetaInfo>

      <Name>Example Tool</Name>

      <Description>Example Description</Description>

      <ToolVersion>1</ToolVersion>

      <CategoryName/>

      <Author>Ira Watt</Author>

      <Icon/>

    </MetaInfo>

  </Properties>

</Configuration>

 

The metadata information is contained within each tag. For example, to change the tool installer’s name, simply change the text contained between the <Name> and </Name> tags.

 

The simplest way to create your Config.xml file is to copy the above example into notepad (any text editor should do), change the details as appropriate, and save it as Config.xml. It is very important to save the file exactly as Config.xml, as that is what Alteryx will look for when opening the yxi file.

 

The final step is to package the Macro(s) up. To do this, put your macros into folders in the same directory as your Config.xml file. After that, highlight them all and zip them up. With the new zip file, change the extension to yxi, and you are done!


Full Gif walkthrough:

 

Zipping YXI.gif

In the gif above, we have two Macros, which are then put into separate folders, zipped together with the config file, and zipped into a yxi. This is the same process for 1 to 100+ Macros. This process also works if we put all the macros in one folder and is entirely down to preference.

 

If you are on Windows and have any troubles changing the file extension, go to view in File Explorer and make sure this box is ticked:

 

tool1.png

 

One last thing to note about macros is the meta info within the macros which defines its tool information. To define information such as which Tool Category the macro will appear in, go to the workflow configuration -> Meta Info and change the category:

 

MeganDibble_1-1662135339114.png

 

And voila:

 

MeganDibble_0-1662136885703.png

 

Source: GIPHY

 

Creating a yxi from the SKD CLI

 

Unlike Macros, the SDK automates the whole process of packaging tools through a CLI (Command Line Interface). The two requirements to set this up are a Python environment with the SDKEnv setup and a Node and NPM version compatible with the SDKEnv. Full details on the environment requirements and setup can be found here: Platform SDK Quickstart Guide | Alteryx Help.

 

Once you have the CLI installed, you can run these three commands to create your Tool Installer.

 

To create your workspace:

 

ayx_plugin_cli sdk-workspace-init

 

To create your Tool:

 

ayx_plugin_cli create-ayx-plugin

 

Finally, to create your tool installer in the build/yxi/ directory:

 

ayx_plugin_cli create-yxi

 

Full details on the parameters for each of these commands can be found here: AYX Plugin CLI Commands | Alteryx Help


Gif walkthrough:

 

CLI YXI.gif

Conclusion

 

Alteryx Installer files are a great and practical way to share tools. Once you have gotten the hang of it, the process is very easy to set up.

 

Please comment below if you have any questions!

Comments
mceleavey
17 - Castor
17 - Castor

noice.gif

MeganDibble
Alteryx Community Team
Alteryx Community Team

I wish this blog article had existed a year ago when I tried to do this and kept getting stuck--thanks Ira for the great tutorial! 

TheOC
15 - Aurora
15 - Aurora

Awesome stuff @IraWatt !

IraWatt
17 - Castor
17 - Castor

Thanks all 😄 @MeganDibble glad I wasn't the only one to get stuck when starting off, it is amazing how many ways there is to incorrectly zip some files 😅

albert_alaluf
9 - Comet

Great blog, and explanations. I postponed .yxi creation many times which I was thinking it was a complex issue. 1-2-3 and done! 

Big thanks!!!😁

cgoodman3
14 - Magnetar
14 - Magnetar

Top marks on the present wrapping gif!


It’s great to highlight this as it is much better way of sharing macros so they appear in a specific tool category on the canvas.

It would be great if a new feature could be added in a similar way to how you can export workflows as yxzp, so that it you are building a yxmc file that the package option includes a yxi option, as not all users will have access to CLI due to organisation IT permissions.

IraWatt
17 - Castor
17 - Castor

Thanks @cgoodman3 😄 I completely agree there should be a simple menu option.

FlorianC
Alteryx
Alteryx

Great article @IraWatt.

 

For those that would like to automate this process but cannot use the SDK, I have created a small PowerShell module that provides helper functions for Alteryx. It contains a dedicated New-AlteryxPackage function that will perform all the necessary steps for you, hopefully in a friendlier way.

severhart
8 - Asteroid

Love this! I just started digging into Macros and I think that this will be really helpful to distribute them when the time comes!

Imran_Ali
6 - Meteoroid

I am unable to get the installed tool in the specified tool category

IraWatt
17 - Castor
17 - Castor

Hi @Imran_Ali if you are using a macro based tool you just need to specify the Category in the Meta Info tab of the workflow configuration.

Imran_Ali
6 - Meteoroid

Thanks @IraWatt. It worked

DataNath
17 - Castor

Thanks for such a clear walkthrough @IraWatt! I've already released a handful of macros but moving forward would love to produce them as tools and even package a few together, with correct categories etc under a .yxi - this will come in super helpful!

Akhand_Singh
6 - Meteoroid

Hi Ira, thanks for this amazing information. But i am struggling with one issue while saving it on to the server. The error says "[new_workflow.yxmd] Tool 1 - Cannot find the macro (macro name which is installed when i installed the Installer)" 

I am using ExoInsight Installer here. Thanks in advance for your help.

 

 

IraWatt
17 - Castor
17 - Castor

Hi @Akhand_Singh, interesting problem. Did how did you install the Tool on the Server? If you login to the server can you see the tool in the \USERNAME\AppData\Roaming\Alteryx\Tools\ folder?

The_Rad_Valentina
8 - Asteroid

I thought only cool kids knew how to do this, and I was right! @IraWatt  Thanks for sharing, now we can be part of the cool kid club as well!

IraWatt
17 - Castor
17 - Castor

Exactly @The_Rad_Valentina 🤣 !!