Quick Start with Custom Tools

Prerequisites

Creating custom tools involves working with several SDKs. For this reason, we assume you are familiar with:

  • HTML
  • JavaScript
  • Python, C++, or Alteryx Macros
  • File management

To demonstrate the process of creating a new tool, we will use a Hello World example so you can meet Alteryx 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.
    3. \HelloWorld
  3. Create an icon to represent the tool within Alteryx. Save the icon inside the tool folder.
    4. \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.
    5. ClosedHelloWorld 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.
    6. \HelloWorld\HelloWorldGui.html
  6. Choose which back end you want to use for your tool.
    • 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.
      • ClosedHello 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 the C++ SDK, 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, such as 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. If your tool uses the Python SDK as its engine, the tool name, as defined in the <Name> tag of the configuration file, cannot contain spaces or special characters. For legibility, camel case is recommended.

    ClosedHello World tool configuration file example

    To change to a different engine type, you would need to change the EngineSetting attributes and the RootToolName.

    <AlteryxJavaScriptPlugin>
	<!-- The connection to the engine that controls the tool's functions. -->
	<EngineSettings EngineDll="Macro" SdkVersion="10.1" 
	EngineDllEntryPoint="HelloWorld\Supporting_Macros\HelloWorldMacro.yxmc" />
	<!-- The connection to the front end that is presented to the user.
	If your tool has any data connections, nest them within the GuiSettings element. -->
	<GuiSettings Html="HelloWorldGui.html" Icon="helloWorld.png" SdkVersion="10.1">
	</GuiSettings>
	<Properties>
		<MetaInfo>
			<NameIsFileName value="false" />
			<Name>Hello World</Name>
			<Description>Designer wants to say hello!</Description>
			<RootToolName>HelloWorldMacro.yxmc</RootToolName>
			<ToolVersion>1.0.0</ToolVersion>
			<ToolInDb value="false" />
			<CategoryName>SDK Examples</CategoryName>
			<Author>Alteryx, Inc.</Author>
			<Company>Alteryx, Inc.</Company>
			<DescriptionLink actual="" display="" />
		</MetaInfo>
	</Properties>
</AlteryxJavaScriptPlugin>
  8. Save the tool configuration file in the tool folder.
    9. \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.
    10. ClosedHello 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. \Config.xml
  11. Package your files in a .yxi for distribution. The .yxi file installs your tool in Alteryx 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.

Build your own tool checklist

Create a folder with the name of your tool. See Build Custom Tools.

Create icon and save it inside the tool folder. See Build Custom Tools.

Create a GUI file and save it inside the folder. See HTML GUI SDK.

Create your back end and save it inside the folder. See C++ SDK, Macro, and Python SDK.

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. Package a Tool.

Package the package configuration file and tool folder as a yxi. See Package a Tool.

Alteryx Help & Documentation | Alteryx Release Notes

Alteryx.com | Community | Customer Support | Documentation Feedback

Copyright © 2018 | Alteryx, Inc. | Alteryx Developer | Beta