(Exciting news! Version 2 of the Auto Documenter tool can be found in an updated blog post. Check out the new post by @levsol, with links to the tool, documentation, demo and contact info!)
Do you ever have those moments in life where one particular topic or idea seems to come up in multiple conversations with different people, seemingly unrelated and coincidental, but the idea is so specific and pops up enough in a short period of time that you think the universe just must be trying to make you pay attention? I love those moments. They make me ponder the interconnectedness of all things, people and ideas. They make me think “something interesting is going on here.”
I had such a moment this year during US Inspire in Anaheim. An idea was pitched in a couple of different ways, by a couple of different people, with a few different primary values being pointed out.
What if there was a way to automatically generate a catalog of all the summarizations and formulas that are being used in a massive workflow, so that I can quickly audit what transformations are happening?
How can we successfully communicate to others what a workflow entails, without having to take screenshots and manually write out a description of the workflow’s actions? Moreover, what do we do when that level of auditing doesn’t suffice for regulatory bodies?
What if we had an easier way to visualize the transformation path a particular data field went through from a workflow’s input all the way down to its output?
The challenges around workflow documentation come up in the solutions center; it is the targeted topic of conversation from an excited customer; it is pitched to me from another Alteryx employee over an after-work glass of wine as an “I heard this really great idea from a customer today” conversation. Ok, universe… I’m paying attention.
Well, on this idea, the Alteryx universe has really kicked it up a notch. Not only have you (our beloved customers) given us some great food for thought around the importance of being able to audit your workflows and document the data transformations, but we have a clever group of customers cooking up something really special. Understanding that we in the Alteryx Development Center (here in lovely Broomfield, Colorado) can’t always move as fast as we want to on all the great product ideas we hear from you, they have decided that this sounds like a problem that the Alteryx product itself can help to solve. This crafty crew of users has been collaborating to bring the Alteryx community a crowd-sourced project for building a solution in Alteryx with Alteryx. I am excited to share with you all today, project AAD (Automated Alteryx Documentor). This customer-led initiative starts here, with a beta version of this customer-created Alteryx app.
Huge kudos and credits go out to all of those involved to make this a reality: Raz Nistor and Kevin Maroney with Keyrus; Bryan Adel, Zach Brookler, Jean Schiele and Richard Balter with Express Scripts; Northern NJ User Group for their ideas and support! You are all rock stars!
Here’s how it works
An Alteryx Analytic App has been created to let you point to the workflow you would like to document.
Click Run as Analytic App button
Choose your workflow
Select the YXMD file you’d like to document and click Finish (hint: you may need to change File Types to search for all files). At this point, the magic starts. The workflow uses an XML reader macro to organize and parse the workflow XML into distinct data sections for each supported tool. These data points are then fed into Alteryx Reporting tools to piece together sections of your output report. Take a sip of coffee (I bet it’ll be too fast for you to have time to get a refill) and voilà! A PDF report is generated that begins telling you the story of the workflow.
Guts of the XML reader
Guts of the app
Sample report page 1 (click to enlarge)
Sample report page 2 (click to enlarge)
Sample report page 3 (click to enlarge)
Sample report page 4 (click to enlarge)
Sample report page 5 (click to enlarge)
Pretty awesome, don’t you agree?! So far, the list of supported tools includes Input, Output, Formula, Select, Summarize, Sort, Join, Union, Regex & Filter. I’m hoping by now we really have your brain thinking on all the other cool functionality that could be useful here.
There’s so much more that could be done!
This is where the Auto Documentation team is looking for your help! One of the most fun parts of the project in my opinion is that customers are driving this initiative and users are coming together to make it happen. They’re looking for your help by crowdsourcing this project and asking you to bring your ideas and Alteryx workflow development skills to table. Here’s how you can get involved.
Next steps
This initial workflow will be hosted on GitLab. Improvements and updates will be incorporated into the primary version, and the plan is to release the Automated Alteryx Documentor to the Public Gallery once the app is in a great working state! From there, Alteryx users all over the world can take advantage of an automated way to include documentation as part of their workflow.
Need some ideas for how to contribute?
Here are some improvements the team has already brainstormed and would love to see added in:
- How can we get around having to create an XML Parse branch for each newly supported tool? Is there a more efficient parsing mechanism that can be built in?
- Similarly, in order to generate the report document, currently a separate set of Reporting tools must be used for each newly added tool. How can this be built more efficiently?
- Support more tools! Where to start, you ask? Maybe you could be a snowflake and add in the Unique tool!
I hope you’ve enjoyed reading through this fun example of customer ingenuity; I know I certainly have enjoyed seeing it come to fruition! The excitement and creativity I’ve witnessed from those involved made me want to help, and I hope it does the same for you. There’s no better way to solve a problem than to open it up to a crew of Alteryx users and let the brilliance begin.