Beyond Alteryx Macros – The Alteryx SDK and API Landscape

/ 4-Oct-2017

All the languages

I started blogging about the Alteryx SDKs about 15 months ago (Introduction to the SDK) to advertise its existence and show what is possible. At the time I wrote that first post, Alteryx 10.6 was the current version. The HTML/JavaScript SDK had been added in version 10.1 (as announced by Ned).

Having just attended Inspire Europe 2017, I thought it would be a good time to review what the Alteryx developer landscape looks like today. I heard a lot more people talking about the developer tools, and I got to meet some other community members using them, as well as giving some demos to a few people. Tasha Alfano is now the product manager of these tools, and she gave a talk on Unlocking the Secret of SDKs and APIs at London.

The idea of this post is to give a quick overview of all the options and some links to resources to get started (to highlight some of the stuff out there!). As I write or find more resources, I will try to keep this post updated.

General Getting Started Resources

  • Alteryx API & SDK Readme: [AlteryxInstallDirectory]/APIs/readme.pdf contains a quick introduction to APIs and SDKs
  • Please note that at least as of v11.5, you no longer need a password to access AlteryxSDK.zip file.

Alteryx’s Various SDKs and APIs

SDK and API Universe

From a developer perspective, there are various places you can hook in and use or extend Alteryx. The APIs and CLI allow you use Alteryx outside of the Designer or Server. The SDKs concentrate on expanding the capabilities of Alteryx. The C++ SDK has been part of Alteryx since the beginning (well version 1.5) and the stability is remarkable. This screenshot is in the sample code in 11.5:

Alteryx v1.5!

Alteryx Server has REST APIs allowing for administration and execution of workflows. Two new server products have been added to the Alteryx product line up (Connect and Promote). I can’t comment much on these yet but know Promote presents REST APIs and I expect Connect does as well. For this post, I am looking at the capabilities of Designer and the Engine.

APIs and CLI: Using the Engine Outside Designer

APIs

As before, I still haven’t done much with the APIs. You will need either a Designer with Desktop Automation license or a Server license to use these. If you don’t have either of these, you can ‘rent’ a server within a cloud VM in either AWS marketplace or Azure marketplace to try them out.

The APIs provide a way to embed an Alteryx Wizard (the original name for Analytic Apps) or Module (workflow) within .Net. What’s fun is you can also dynamically generate XML an run it within the engine. You can run the engine either within the same process or a separate process connected by a named pipe. Within the C++ SDK, there is also an Alteryx Engine API allowing you to do the same in native C++.

The CLI in Alteryx is a command line tool allowing you to run a workflow in the engine. I have been using this a lot as part of my unit testing. It is called by running AlteryxEngineCmd.exe. The syntax is:

AlteryxEngineCmd.exe Version 11.5.1.31573 © Alteryx, Inc. - All Rights Reserved.

Usage:
AlteryxEngineCmd MyModule.yxmd

or
AlteryxEngineCmd MyAnalyticApp.yxwz AnalyticAppValues.xml

or
AlteryxEngineCmd AnalyticAppValues.xml
        Runs the Analytic App contained in the <Module>Path</Module> tag of AnalyticAppValues.xml

or
AlteryxEngineCmd /Encrypt Mymodule.yxwz Output.yxwz [CommaSeparatedSerialNumbers [ExpirationDate]]

Returns: 0 - Success, 1 - Warnings Exist, 2 - Errors Exist

API Getting Started Resources

  • Getting Started with the Alteryx APIs: [AlteryxInstallDirectory]\APIs\SampleCode\Getting Started with the Alteryx API.pdf
  • Class Documentation:
    • .Net: [AlteryxInstallDirectory]\APIs\AlteryxEngineAPI.chm contains documentation of all the .Net APIs
    • C++: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\Documentation\AlteryxSDK.chm within the Alteryx Engine section
  • .Net Samples: All within [AlteryxInstallDirectory]\APIs\SampleCode\
    • AlteryxApiSample: – Sample project to run an Analytic App, pass in parameters, and consume data
  • CLI Syntax help: Run AlteryxEngineCmd.exe in the [AlteryxInstallDirectory]/bin/ with no parameters to display command syntax
  • Server API: Excel to Alteryx API by Patrick Digan

SDKs: Expanding Alteryx’s Tools and Capabilities

The SDKs concentrate on expanding Alteryx’s functionality. Specifically in two areas:

  • Custom Function for expressions
  • Custom Tools

The picture below shows the vast range of choice available to you:

SDK Choices

Custom Functions

These can be written in either just XML or using C++ and allow you to expand the set of functions available within Alteryx expression engine. Please note, unlike custom tools, this is not the same SDK as core team use. There are also some limitations as to what is possible (e.g., it is not possible to handle Spatial types within the C++ SDK).

Installation is only supported by copying the XML and copied DLL files to the [AlteryxInstallDirectory]\bin\RuntimeData\FormulaAddIn\ folder. My Alteryx Abacus project has some installation scripts which can be used to help with this.

Custom Functions Resources

  • Documentation: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\Documentation\AlteryxSDK.chm within the Custom Formulas section
  • Sample: Simple demo of an XML function converting a string to title case [AlteryxInstallDirectory]\bin\RuntimeData\FormulaAddIn\Sample.xml. Can be run by calling SampleFormulaAddInFormula('hello world').
  • Sample C++ Formula AddIn: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\AlteryxPluginAPI\FormulaAddInSample contains 3 simple sample C++ functions (Add, Concat, Multiply)
  • Starter XML AddIn: Simple demo function and Installer
  • Starter C++ AddIn: Simple C++ based demo function (with Visual Studio 2017 project) and Installer
  • Beyond Alteryx Macros: How To Create An Xml Macro Function
  • Alteryx Abacus Install Scripts
    • Install.bat: UAC promoter calling Installer.ps1
    • Installer.ps1: PowerShell based installer for formula DLL and XML files (requires PowerShell v3)
    • Install Win7.bat: Batch file handling UAC and installation on Windows 7
    • Uninstall.bat: UAC promoter calling Uninstaller.ps1
    • Uninstaller.ps1: PowerShell based uninstaller for formula DLL and XML files (requires PowerShell v3)
    • Uninstall Win7.bat: Batch file handling UAC and uninstallation on Windows 7
  • Open Source Projects:

Custom Tools

There is a wide range of choices for developing custom tools for Alteryx. You need to build two parts for a new tool – a configuration GUI and an engine. There is, however, no need to do this in the same language – and hence there is a wide spectrum of choices open to you. The list shows the options with built-in examples found in version 11.5:

I included Macros in here as they are often the best and easiest way to create new tools. It is always worth considering these before jumping into the SDK. At present (as of version 11.5), the HTML/JavaScript SDK is in Beta, and the Python SDK is an Alpha release (and only in the Admin install version).

Installation of custom tools currently varies depending on platform. For macros, it is just a case of copying the yxmc into a specific folder as you choose within your User Settings. You can also just use a macro directly. Adam Riley has built an Analytic App for installing his amazing CReW macros, this can be adjusted relatively easily if you want to distribute macro packs.

If you have an HTML UI with Python, HTML or a Macro for the engine, then these can be packaged as YXI files which when run will install into Alteryx. As The Information Lab’s Peter Gamble-Beresford blogged you can also use YXI for distributing macros.

YXI Install Screen

For .Net or C++ based engine tools or WinForm based UIs; you need to add an ini file to load the dll into the [AlteryxInstallDirectory]\Settings\AdditionalPlugins. The YXI installers don’t currently support these style of tools.

One other aspect to consider is debugging. The older SDKs (C# and C++) have very strong debugging support. If you run Alteryx from within Visual Studio, it will automatically run the engine within the same process allowing you to debug the engine side of the tools easily. Likewise, it is possible to debug the WinForms code of the UI as easily. The JavaScript UI has the advantage that changes are reflected just by refreshing the configuration panel. I am not aware of any easy way to debug JavaScript- or Python-based engine tools at present.

Custom Tool Resources

  • Documentation:
    • .Net: [AlteryxInstallDirectory]\APIs\SampleCode\DotNetCustomTools.pdf contains a slightly dated, but accurate, guide on how to build .Net based tools
    • C++: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\Documentation\AlteryxSDK.chm within the Custom Tools section
    • JS: HTML GUI online documentation under development
    • Python: Python SDK online documentation under development
  • Sample C++ / WinForms Tools: Set of sample tools built in C++ with C# WinForms UI
    • C++: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\AlteryxPluginAPI\SDKSampleEngine\SDKSampleEngine.vcxproj contains the C++ engine code
    • C#: [AlteryxInstallDirectory]\APIs\AlteryxSDK.zip\AlteryxPluginAPI\SDKSampleGui\SDKSampleGui.csproj contains the C# WinForms UI code
    • Tool examples include CSV input, CSV output, Subtotal, Summary
  • Sample C# Engine and UI Tools: Set of sample tools built in C# for both UI and Engine
    • C#: [AlteryxInstallDirectory]\APIs\SampleCode\CustomDotNetTools\CustomDotNetTools.sln
    • Tool examples included: XML input, XML output, XML transform
  • Sample HTML SDK Tools: Built in sample tools for the HTML GUI SDK
    • JS v2 API: HTML GUI SDK showing all the controls [AlteryxInstallDirectory]\bin\HtmlPlugins\HtmlGuiSdk\. The engine side puts the two inputs (A, B) together and pushes to the output. Inputs must be the same length.
    • JS v1 API: Javascript Plugin Example showing the v1 of the HTML controls [AlteryxInstallDirectory]\bin\HtmlPlugins\JavascriptPluginExample\. The engine just passes through the input (config file needs to be renamed for it to appear in Designer)
  • Sample Python Tools: Built-in sample tool for the Python SDK
    • Python: Replica of the RecordID tool built in Python [AlteryxInstallDirectory]\bin\HtmlPlugins\PythonSDKExample\. This is in alpha and only in the admin install of 11.5
  • OmniBus Tools: My set of tools built on top of the OmniBus framework
    • C#: Source Code
    • Tool examples include Date Input, Date Parser, String Formatter, Hex Bins, Hashcode Generator, Circuit Breaker, Roslyn Input, Random Number Generator, Number Parser
  • OmniBus Framework: My C# Nuget libraries for creating Alteryx tools
  • Outlook Tool: – C# based tool to connect to Outlook / Exchange Web Services
  • Inspiring Ingenuity (Ned’s Blog): New in 10.1 – HTML SDK
  • Engine Works Blog: The JavaScript Tool
  • Engine Works Blog: The JavaScript Tool Part II – The GUI Edition
  • OmniBus Regex: An experimental HTML UI for the Regex tool
  • OmniBus Typings Files: Typings files for working with the JavaScript SDK
    • TypeScript v1 API: Engine
    • TypeScript v1 API: GUI
  • Beyond Alteryx Macros: Alteryx’s JavaScript SDK: an unofficial guide (with sample Hello from JS tool)
  • Beyond Alteryx Macros: JsEvent, Value Previews, and The Formula Tool
  • Information Lab: How to create and share an Alteryx Tool Installer by Peter Gamble-Beresford

Updates:

  • 2017-10-06: Added How to create and share an Alteryx Tool Installer post and corrected YXI paragraph
  • 2017-10-13: Added Patrick Digan’s post on using Server REST API in Excel

Related posts

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.