Custom Tools Quickstart
Important
These 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!
Note
Prerequisites
Custom tool creation involves working with several SDKs that require familiarity with these:
HTML
JavaScript
Python, C++, or Alteryx Macros
File Management
Overview of Steps to Build a Custom Tool
Create a folder with the name of your tool. See Create a Tool Folder.
Create tool icon .png file and save it inside the tool folder.
Create a GUI file and save it inside the tool folder. See HTML GUI SDK.
Create your back end and save it inside the tool folder. See C++ SDK, Python SDK, or Macro.
Create a configuration file and save it inside the folder. See Tool Configuration File.
Create a package configuration file and save it with the folder. See Package a Tool.
Package the package configuration file and tool folder as a yxi. See Package a Tool.
Example Custom Tool Creation Walkthrough
To demonstrate the process of creating a new tool, we will use a Hello World example so you can meet Designer. Download the complete example to follow along.
1. Create a workspace.
2. Inside your workspace, create a folder with the name of your tool.
\HelloWorld
3. Create an icon to represent the tool with Alteryx. Save the icon inside the tool folder.
\HelloWorld\helloWorld.png
4. Create a file that contains the Graphical User Interface (GUI). This file is constructed using HTML and JavaScript. For more information on how to create and manage the data pulled from the GUI, see HTML GUI SDK.
HelloWorld GUI Example
For Hello World, the tool configuration window has a heading and a check box labeled "Say hi!", defined inside the <h1> and <div> tags respectively. The JavaScript manages the value from the check box and makes the values persistent.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Hello World tool</title>
<!-- Includes the GUI library, which gives you access to the interface elements used in Designer -->
<script type="text/javascript">
document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">');
</script>
<!-- Applies styles to the interface elements you create -->
<style type="text/css">
body {
margin: 15px;
}
#helloCheckBox{
padding-top: 20px;
font-family: "Segoe UI";
}
h1{
text-align: center;
margin: 0 0 0 0;
padding: 0;
}
</style>
</head>
<body>
<h1>Meet Designer</h1>
<!-- Creates a check box with a widgetId to be referenced by engine code and a display label -->
<div id="helloCheckBox">
<ayx data-ui-props='{type:"CheckBox", widgetId:"helloCheckBox", label:"XMSG("Say hi!")"}'></ayx>
</div>
<script type="text/javascript">
window.Alteryx.Gui.BeforeLoad = function(manager, AlteryxDataItems, json){
// Creates a new data item, which can be used to store data.
var greetingsDataItem = new AlteryxDataItems.SimpleBool('helloCheckBox')
/* Binds the data item to the UI element, in this case the check box.
The data item holds a boolean value based on if the check box is selected. */
manager.bindDataItemToWidget(greetingsDataItem, 'helloCheckBox')
// Adds the value to the manager, which then manages data persistence for you
manager.addDataItem(greetingsDataItem)
// Updates the boolean value stored in the data item every time the checkbox is clicked
document.getElementById('helloCheckBox').onclick = function (newCheckBoxValue) {
greetingsDataItem.setValue(newCheckBoxValue.target.value)
}
}
//Retrieves data from data items
window.Alteryx.Gui.AfterLoad = function(manager,AlteryxDataItems){
var greetingsDataItem = manager.getDataItem('helloCheckBox')
document.getElementById('helloCheckBox').value = greetingsDataItem.getValue()
}
//creates a string to display the returned value, in this case the value of the check box
window.Alteryx.Gui.Annotation = function(manager){
var greetingsDataItem = manager.getDataItem('helloCheckBox')
return greetingsDataItem.getValue()
}
</script>
</body>
</html>5. Save the GUI file inside the tool folder.
\HelloWorld\HelloWorldGui.html
6. Choose which back-end you want to use for your tool.
Alteryx Macros
Alteryx Macros: To use an Alteryx Macro, see Macro.
Open Alteryx Designer and navigate to the Interface category. Use these tools to create the connection between the HTML interface and the macro. Ensure the workflow type is set to a macro. Download the Hello World Macro Engine Example.
Save your macro in a \Supporting_Macro folder within your tool folder.
\HelloWorld\Supporting_Macros\HelloWorldMacro.yxmc
Python
For installation instructions or information on how to use the Python SDK, see Python SDK.
Hello World Python Engine File Example
""" Provides access to the Python SDK classes """
import AlteryxPythonSDK as Sdk
""" Allows for easy manipulation of the xml used to hold tool information """
import xml.etree.ElementTree as Et
""" The building block class for using the Python SDK """
class AyxPlugin:
""" initializes the instance of the tool """
def __init__(self, n_tool_id: int, alteryx_engine: object, output_anchor_mgr: object):
self.n_tool_id = n_tool_id
self.alteryx_engine = alteryx_engine
self.output_anchor_mgr = output_anchor_mgr
""" connects with HTML checkbox """
self.checkBoxValue = "False"
""" pulls value from annotation """
def pi_init(self, str_xml:str):
self.checkBoxValue = Et.fromstring(str_xml).find('helloCheckBox').text
self.alteryx_engine.output_message(self.n_tool_id, Sdk.EngineMessageType.info,
self.message_to_display(self.checkBoxValue))
""" method required with no input, but does not push records in this tool """
def pi_push_all_records(self, n_record_limit:int) -> bool:
return True
""" required after pi_push_all_records """
def pi_close(self, b_has_errors:bool):
return True
""" evaluates to get the output message """
@staticmethod
def message_to_display(checkBoxValue):
if checkBoxValue == "True":
return "Hello World!"
else:
return "You didn't say hi"Save your Python engine file in the tool folder.
\HelloWorld\HelloWorldPythonEngine.py
C++
For information on how to use, see C++ SDK.
Save your C++ engine file in the tool folder.
\HelloWorld\HelloWorldCPlusPlusEngine.cpp
7. Create a tool configuration file. This file contains the information that Designer uses when installing the tool, like the tool name and the category in the tool palette. It also contains the location of the files that comprise the tool engine and GUI. See Tool Configuration File.
8. Save the tool configuration file in the tool folder.
\HelloWorld\HelloWorldConfig.xml
9. Create a package configuration file. This .xml file contains the information that displays in the installer, such as the tool name, the icon that will display, and what category to expect the tool to appear in once installed. See Package a Tool.
Hello World Package Configuration File Example
<?xml version="1.0"?>
<Configuration>
<Properties>
<MetaInfo>
<Name>Hello World</Name>
<Description>Designer wants to say hello!</Description>
<ToolVersion>1.0.0</ToolVersion>
<CategoryName>SDK Examples</CategoryName>
<Author>Alteryx</Author>
<Icon>HelloWorld\helloWorld.png</Icon>
</MetaInfo>
</Properties>
</Configuration>10. Save the package configuration file at the same level as the tool folder.
11. Package your files in a UXI for distribution. The YXI file installs your tool in Designer. See Package a Tool.
Zip the tool folder and the package configuration file into a zip folder.
Rename the zip folder to have a YXI extension.