community
cancel
Showing results for 
Search instead for 
Did you mean: 

Engine Works Blog

Under the hood of Alteryx: tips, tricks and how-to's.
Sr. Community Content Manager
Sr. Community Content Manager

Almost two years ago, @Ned made a tool that emulates the Alteryx Formula tool, but instead of building an Alteryx expression, you write JavaScript code. About a year later, as part of our Innovation Days - two days each quarter for the development organization to work on their own side projects - I made a similar tool, this time inspired by the R tool rather than the Formula tool. Ned blogged about his tool to celebrate the unofficial release of the HTML SDK. As we get closer to the official release of the SDK later this year, I decided to dust off the code I wrote a year ago and share it here. In this post I'll describe how you can use this experimental tool. I'll follow up with a second post about how I created the tool's user interface, and then finish the series with a third post explaining how the back-end works.

 

Installation

Download the yxi file. Open the file in Designer (or just double click on the file) to install. The tool will then appear in the Developer category of the tool palette.

 

How to use it

The tool's interface is fairly simple. There is a text box to list script files you'd like to include (like jQuery), a code editor, and a button that allows you to insert into the code editor functions that allow your code to interact with Alteryx. When you insert these functions they come pre-commented with a sentence or two about what the function does. Those comments (along with this post) constitute the tool's documentation at this point. 

 

The fastest way to get the tool to do something is as follows, and actually requires no typing:

  1. Drag the tool onto the canvas.
  2. Hover over the "Insert Code" button and click "Write Metadata".
  3. Then click "Write Data".
  4. Run the workflow.

js1.gif

 

The first function you just inserted, writeAlteryxMetadata, tells Alteryx what fields are going to come out of the JavaScript tool. The second function, writeAlteryxData, pushes data out of the tool. Both functions come pre-populated with arguments that show the format of the data that the functions are expecting. There's a third function, notifyAlteryxComplete, pre-populated at the bottom of the code editor, that tells the tool you're done. You've just created a script that will output two rows of data!

 

Here's how you configure the tool to act as a connector to an API, here using jQuery:

Capture.PNG

 

Here's code demonstrating how to deal with data coming into the tool - this just pushes back out the same data that's coming in:

writeAlteryxMetadata(readAlteryxMetadata())
writeAlteryxData(readAlteryxData())
notifyAlteryxComplete()

And here's code that makes the tool add 1 to the incoming data:

var incomingData = readAlteryxData()
writeAlteryxMetadata([{name:'plus1', type:'Double'}])
for (i = 0; i < incomingData.length; i++) {
   writeAlteryxData([[incomingData[i][0] + 1]])  
}
notifyAlteryxComplete()

All of the above example usages are included in the workflow attached to this post.

 

The top two use cases I can think of for why this tool would be useful are:

  1. To use as a connector to download data from web REST APIs. The Download tool is awesome, and most of the time it will be easier to use than the JavaScript tool, even for experienced JS developers. But sometimes APIs are tricky to use and you might just want to copy and paste some JS code from a sample that the API docs provide, rather than try and figure out how to get it working with the Download tool.
  2. To use as a JSON parser to sift through complex objects. Again, the JSON Parse tool will often be easier to use for this purpose than this tool, but if you have a very complex object and you need to get at some data that's deeply nested inside the object, this tool (along with Lodash) could help. After all, the JS in JSON stands for JavaScript.

There are so many JS libraries out there that I'm sure there's a bunch or things you can do with this tool in Alteryx that I couldn't even dream of. I'm hoping some of you come up with other interesting use cases - let me know in the comments.

 

P.S.

Why do I call this tool "experimental"? Cuz it has issues. One is that error handling is tricky. Designer could hang if you don't properly handle errors and have a notifyAlteryxComplete function call at the end of every code path. I try to take care of this for you in the back-end (wait for part III for more detail on this), but for ajax, you'll need to do this on your own.

Here's an example: 

$.get({
  url: "http://dev.arkitondemand.com/MODApis/Api/v2/Quote/json?symbol=AYX",
  dataType: "json",
  success: function (data) {
    writeAlteryxMetadata([{name:'JSON', type:'String', size:1000}]);
    writeAlteryxData([[JSON.stringify(data)]]);
    notifyAlteryxComplete();
  }
})

In the code snippet above, the URL is misspelled. I've written "arkitondemand" instead of "markitondemand".  Because I don't have an error callback function, the notifyAlteryxComplete function never gets called, and Alteryx hangs - you need to manually cancel the workflow or else it will keep running forever. So be careful!

The right way to do this is as follows:

$.get({
  url: "http://dev.markitondemand.com/MODApis/Api/v2/Quote/json?symbol=AYX",
  dataType: "json",
  success: function (data) {
    writeAlteryxMetadata([{name:'JSON', type:'String', size:1000}]);
    writeAlteryxData([[JSON.stringify(data)]]);
    notifyAlteryxComplete();
  },
  error: function (err) {
    logAlteryxError(JSON.stringify(err));
    notifyAlteryxComplete();
  }  
})

 

P.P.S.

Shout out to CodeMirror and W3Schools - more about how they helped in part II.

 

Another shout out to @jdunkerley79 - if you want more information about how the HTML SDK works but can't wait for the official release, or even my next post, check out his recent post here.

Neil Ryan
Sr Program Manager, Community Content

Neil Ryan is the Sr Program Manager, Community Content, responsible for the content in the Alteryx Community. He held previous roles at Alteryx including Advanced Analytics Product Manager and Content Engineer, and had prior gigs doing fraud detection analytics consulting and creating actuarial pricing models. Neil's industry experience and technical skills are wide ranging and well suited to drive compelling content tailored for Community members to rank up in their careers.

Neil Ryan is the Sr Program Manager, Community Content, responsible for the content in the Alteryx Community. He held previous roles at Alteryx including Advanced Analytics Product Manager and Content Engineer, and had prior gigs doing fraud detection analytics consulting and creating actuarial pricing models. Neil's industry experience and technical skills are wide ranging and well suited to drive compelling content tailored for Community members to rank up in their careers.

Comments
Bolide

 This could be useful for scraping web pages and using the various DOM methods available in javascript/jquery.

 

I usually just use the DL tool or the CMD tool with a headless browser to pull down the rendered page and the use regex to hack out what I need.

 

JS would certainly be more efficient but then again I would have to dust off my limited JS "skills" which makes me sad.

Alteryx
Alteryx

I wanted to update this thread to let you know that we have new SDK documentation available for our HTML GUI SDK, which was released in as a beta in 11.5. You can find documentation for both the HTML GUI SDK online. We'd love for you to provide your feedback here

Hey Neil - 

 

How could we tweak this tool to be used to in conjunction with an interface drop down box to generate a list of choices for a user once they've started typing?  I had a situation wherein I need a gallery user to select an address, but there are ~ 100K of them, so populating a drop down doesn't help.  If they type the wrong address, the workflow will run, but then come back with nothing and/or an error message, 'are you sure about this address'.  But the reality is our address data is horrible and it's easy to miss fire.  I needed to give our users the ability to start typing, see a list of addresses that made sense, choose one, and then start blasting away with the workflow.   

 

The eventual solution I came up with was writing an ajax call on a standalone js page to goto the database once the user started typing, give them a list of matches that I knew were in the database, and then on selection, passing that value on to a service to invoke calls to gallery using the API / Open Auth, passing the resultant messages and files back to the html page and serving up to the browser.  A total hassle to get around what on the face of it is a very simple web operation, auto complete.  

 

I'm also going to post to the ideas forum.  

 

Thanks. 

brian

 

 

Sr. Community Content Manager
Sr. Community Content Manager

@brian_scott the HTML SDK is used to build dynamic interfaces for tools in workflows (like the tool described in this post). I think your approach of building a custom interface for an analytic app by leveraging the Gallery API is correct.

Asteroid

Great article, thanks @NeilR, I am dabbling in Javascript and thought this tool could be exactly what I needed for a particularly troublesome API. How can a user specific run-times and libraries like Node.js? Is it similar to how you're importing jquery?

 

Also, does this tool support ES6?

 

Edit: on a related note, is there any more documentation on how to output the other fields on the same record that some javascript data manipulation was performed on? It's not quite clear how this is done currently. I am simply returning "[field] has length of 0" errors

 

Sr. Community Content Manager
Sr. Community Content Manager

@aMac

 


How can a user specific run-times and libraries like Node.js? Is it similar to how you're importing jquery?

node.js is a JavaScript runtime environment, not a library like jquery. Alteryx executes its JS code in a different runtime environment - Chromium. Node is not supported.

 

Also, does this tool support ES6?

Chromium supports ES6 as of version 52. You can check what version of Chromium Alteryx is running by adding logAlteryxMessage(navigator.userAgent) to the JavaScript tool. The version will appear in the log. My version of Alteryx (2018.3) is running Chromium v62...

 

log1.PNG

 

on a related note, is there any more documentation on how to output the other fields on the same record that some javascript data manipulation was performed on? It's not quite clear how this is done currently. I am simply returning "[field] has length of 0" errors

The readAlteryxData() function returns the incoming data as an array of arrays - the higher level array elements representing the records and the embedded array representing each field within. So incoming data that looks like this...

 

data1.PNG

 

...is represented like this:

data2.PNG

So if you wanted to multiply the first column by 2, and leave the other columns alone:

metaData = readAlteryxMetadata()

data = readAlteryxData()
logAlteryxMessage(data)

for (i = 0; i < data.length; i++) {
	data[i][0] = data[i][0]*2
} 

writeAlteryxMetadata(metaData)
writeAlteryxData(data)

notifyAlteryxComplete()

 

Labels