Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
The Alteryx Gallery API enables you to run Alteryx apps or workflows remotely from other applications or other workflows/apps. You might be wondering to yourself why/when would I ever need to do this? Let’s walk through a couple of the use cases for this.
Use Case 1: Dependency Based Scheduling in the Gallery
You may have used the CreW Macro toolset and scheduled “Runner” workflows to trigger and run all of your jobs in dependency-based ordering. This is an effective method but runs into issues when your workflows/apps are in the Gallery and are not stored on disk. You might then refute that the simple solution is to keep things on disk; but this negates a lot of the Gallery benefits:
- Sharing
- Security Provisioning
- Version Control
- Backup/Restore
If you have published your workflows/apps to the Gallery and run into this issue of dependency then the Gallery API can help. Similar to the “Runner” workflow, you can have workflow(s) scheduled to the Gallery that run other Gallery-based workflows/apps and set-up proper dependency. I have had to do this for clients, and it is an effective strategy to overcoming this limitation.
Use Case 2: Access to the Gallery Interface is Restricted or Not Desired for End Users
Perhaps the limitation is you want users to trigger apps or workflows but either have the Gallery in restricted security zones or do not want them to access the Gallery directly. The API is an effective way around this as well. You can call the API through another application where the end user does have access to. Some instances I have helped clients work through this with include JIRA and custom web pages/company websites.
These custom websites and applications can interface to Alteryx Gallery through the OAuth 1.0a API. The end user can have a custom-made interface and use forms on that interface or other triggers that will prompt the front-end application to communicate to Alteryx Gallery to run specific workflows/apps with specific parameters as set by the end user.
Now you are thinking, that sounds great, but how do I build an API to communicate to Gallery? The good news is this information, and even macros, are built and ready for your consumption. If you are looking to build the API from a front-end application or custom webpage, you can find the appropriate documentation here:
http(s)://[YOUR GALLERY]/gallery/api-docs/
This page is a great resource that comes with any install of Alteryx Gallery. It provides a sample page where you can read-up on how to create the API calls and even allows you to test them from this page.
In order to properly send API calls to the Gallery you need an API Key and Secret to make the API calls. You can find these under your user account > settings:
There are two API credentials you can see. One is for calling workflows/apps for your private studio and the other is to perform admin functions such as get a list of schedules, collections, users, workflows, etc.
Now to recap, we have covered why and how you would make an API call to the Gallery. But what if you do not want to write a custom application and instead want to call it using Alteryx itself, such as in the dependency use case. You are in luck because this has already been created for you by Alteryx, you just need to know where to find it and how to leverage it.
If you install the Alteryx Connect Metadata Loaders, inside contains loaders for many applications/databases; but most notably is the Alteryx Server itself. Inside the Alteryx Loader there are two main macros that contain other nested macros used to communicate with the Gallery. These can be modified to suit your needs including chaining jobs, downloading workflows, running workflows, etc. I have attached them to this article for you to leverage.
This macro does all of the OAuth 1.0a API formation for you and you can just modify the endpoints or parameters to perform specific actions.
Typical errors to watch out for when making the API calls to the Gallery include/should be verified:
- Ensure End-Point is correct; most notably the Gallery URL.
- Ensure the App ID/Workflow ID is correct. This is in the URL page for the Gallery.
- Ensure the correct Key/Secret are being used for Admin or Private Studio and that they match.
These encompass the majority of the issues and by reviewing/confirming these the problem will most likely be resolved; assuming the attached macro tool is being used.
This concludes the tutorial on the benefits of the Gallery API and how to utilise it to your benefit. It is important to note that as Alteryx Gallery versions update changes to the API may occur and that any production process using the API must be reviewed during your company Gallery upgrades.
