Quick Start with Custom Tools

Version:
Current
Last modified: July 06, 2020

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

  1. Create a folder with the name of your tool. See Create a Tool Folder.
  2. Create tool icon .png file and save it inside the tool folder.
  3. Create a GUI file and save it inside the tool folder. See HTML GUI SDK.
  4. Create your back end and save it inside the tool folder. See C++ SDK, Python SDK, or Macro
  5. Create a configuration file and save it inside the folder. See Tool Configuration File
  6. Create a package configuration file and save it with the folder. See Package a Tool
  7. 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.

HTML
  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4.   <meta charset="UTF-8">
  5.   <title>Hello World tool</title>
  6.  
  7.   <!-- Includes the GUI library, which gives you access to the interface elements used in Designer -->
  8.   <script type="text/javascript">
  9.      document.write('<link rel="import" href="' + window.Alteryx.LibDir + '2/lib/includes.html">');
  10.   </script>
  11.  
  12.   <!-- Applies styles to the interface elements you create -->
  13.   <style type="text/css">
  14.     body {
  15.         margin: 15px;
  16.       }
  17.       #helloCheckBox{
  18.         padding-top: 20px;
  19.         font-family: "Segoe UI";
  20.       }
  21.       h1{
  22.         text-align: center;
  23.         margin: 0 0 0 0;
  24.         padding: 0;
  25.       }
  26.   </style>
  27.  
  28. </head>
  29. <body>
  30.   <h1>Meet Designer</h1>
  31.  
  32.   <!-- Creates a check box with a widgetId to be referenced by engine code and a display label -->
  33.   <div id="helloCheckBox">
  34.     <ayx data-ui-props='{type:"CheckBox", widgetId:"helloCheckBox", label:"XMSG("Say hi!")"}'></ayx>
  35.   </div>
  36.   <script type="text/javascript">
  37.     window.Alteryx.Gui.BeforeLoad = function(manager, AlteryxDataItems, json){
  38.  
  39.       // Creates a new data item, which can be used to store data.
  40.       var greetingsDataItem = new AlteryxDataItems.SimpleBool('helloCheckBox')
  41.  
  42.       /* Binds the data item to the UI element, in this case the check box.
  43.       The data item holds a boolean value based on if the check box is selected. */
  44.       manager.bindDataItemToWidget(greetingsDataItem, 'helloCheckBox')
  45.  
  46.       // Adds the value to the manager, which then manages data persistence for you
  47.       manager.addDataItem(greetingsDataItem)
  48.  
  49.       // Updates the boolean value stored in the data item every time the checkbox is clicked
  50.       document.getElementById('helloCheckBox').onclick = function (newCheckBoxValue) {
  51.         greetingsDataItem.setValue(newCheckBoxValue.target.value)
  52.       }
  53.     }
  54.  
  55.     //Retrieves data from data items
  56.     window.Alteryx.Gui.AfterLoad = function(manager,AlteryxDataItems){
  57.       var greetingsDataItem = manager.getDataItem('helloCheckBox')
  58.  
  59.       document.getElementById('helloCheckBox').value = greetingsDataItem.getValue()
  60.     }
  61.  
  62.     //creates a string to display the returned value, in this case the value of the check box
  63.     window.Alteryx.Gui.Annotation = function(manager){
  64.       var greetingsDataItem = manager.getDataItem('helloCheckBox')
  65.       return greetingsDataItem.getValue()
  66.     }
  67.   </script>
  68. </body>
  69. </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

    Python
    1. """ Provides access to the Python SDK classes """
    2. import AlteryxPythonSDK as Sdk
    3. """ Allows for easy manipulation of the xml used to hold tool information """
    4. import xml.etree.ElementTree as Et
    5.  
    6. """ The building block class for using the Python SDK """
    7. class AyxPlugin:
    8.  
    9.     """ initializes the instance of the tool """
    10.     def __init__(self, n_tool_id: int, alteryx_engine: object, output_anchor_mgr: object):
    11.  
    12.         self.n_tool_id = n_tool_id
    13.         self.alteryx_engine = alteryx_engine
    14.         self.output_anchor_mgr = output_anchor_mgr
    15.  
    16.         """ connects with HTML checkbox """
    17.         self.checkBoxValue = "False"
    18.  
    19.     """ pulls value from annotation """
    20.     def pi_init(self, str_xml:str):
    21.         self.checkBoxValue = Et.fromstring(str_xml).find('helloCheckBox').text
    22.         self.alteryx_engine.output_message(self.n_tool_id, Sdk.EngineMessageType.info,
    23.           self.message_to_display(self.checkBoxValue))
    24.  
    25.     """ method required with no input, but does not push records in this tool """
    26.     def pi_push_all_records(self, n_record_limit:int) -> bool:
    27.     	return True
    28.  
    29.     """ required after pi_push_all_records """
    30.     def pi_close(self, b_has_errors:bool):
    31.     	return True
    32.  
    33.     """ evaluates to get the output message """
    34.     @staticmethod
    35.     def message_to_display(checkBoxValue):
    36.     	if checkBoxValue == "True":
    37.     		return "Hello World!"
    38.     	else:
    39.     		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
      1. <?xml version="1.0"?>
      2. <Configuration>
      3. 	<Properties>
      4. 		<MetaInfo>
      5. 			<Name>Hello World</Name>
      6. 			<Description>Designer wants to say hello!</Description>
      7. 			<ToolVersion>1.0.0</ToolVersion>
      8. 			<CategoryName>SDK Examples</CategoryName>
      9. 			<Author>Alteryx</Author>
      10. 			<Icon>HelloWorld\helloWorld.png</Icon>
      11. 		</MetaInfo>
      12. 	</Properties>
      13. </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.

      1. Zip the tool folder and the package configuration file into a zip folder.
      2. Rename the zip folder to have a YXI extension.
      Was This Helpful?

      Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support.