Skip to content

The Alteryx SDK Landscape

Jump to bottom
James Dunkerley edited this page Oct 3, 2017 · 8 revisions

Beyond Alteryx Macros - The Alteryx SDK and API Landscape

All the languages

I started blogging about the Alteryx SDKs about 15 months ago (Introduction to the SDK) to advertise it existance 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 attend Inspire Europe 2017 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 memeber using them, as well as giving some demoes 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. 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 excution 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 present REST APIs and expect Connect does as well. For this post I am looking at the capabilities within 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 in order 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 easily embedded running 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 within a separate process connected by . 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 alot 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

SDKs: Expanding Alteryx's Tools and Capabilites

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

  • Custom Function for expressions
  • Custom Tools

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

SDK Choices

Custom Functions

These can be writen in either just XML or using C++ and allow you to set of functions available within Alteryx expression engine. Unlike custom tools, this is not the same API 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. This leads to a spectrum of choices (with built in examples in brackets - based on 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 fairly 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.

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 included: 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
  • 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

Home

Developing Functions

Grouped Record ID

Clone this wiki locally