2022.1.1.30569 Patch Release Update

The 2022.1.1.30569 Patch/Minor release has been removed from the Download Portal due to a missing signature in some of the included files. This causes the files to not be recognized as valid files provided by Alteryx and might trigger warning messages by some 3rd party programs. If you installed the 2022.1.1.30569 release, we recommend that you reinstall the patch.

Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
DanH
Moderator
Moderator

Introducing Alteryx Server v3 API endpoints 

 

With the release of Alteryx Server v21.4, there are a series of new Gallery API capabilities. 

 

Purpose of the Updates 

 

If you had used the v1 and v2 endpoints, you will have noticed that they are very similar to one another. V1 and v2 endpoints serve three main use cases: 

  • Workflow Execution 
  • Content Oversight 
  • Workflow Migration 

  

With the addition of the v3 endpoints, you'll notice a much larger set of endpoints, and a focus on administration of Gallery content, including updating, deleting, and creating most types of assets. This ability to programmatically perform CRUD operations on most types of assets allows for a wide variety of administrative use cases, from data-driven user management, to integrated scheduling, to bulk data connection management. Accessing these endpoints is available to Admins (Curator role). 

  

Alteryx Server is moving away from a reliance on Studios for workflow administration to a focus on authorization via Collections. These new v3 endpoints provide new options for this migration, as well as other migration scenarios. 

  

What's New? 

 

One significant change between v1, v2, and v3 is in the authorization mechanism. 

 

Both v1 and v2 endpoints use the same OAuth1.0a method to sign every single request, and therefore don't reuse a token or signature when sending multiple requests. This OAuth1.0a method relies on "signing" a request by generating a string which contains most of the details about the request, including the base URL, serialized parameters, a random nonce, timestamp, and API Access Secret. The resulting string is hashed with HMAC-SHA1, and that "signature" is sent along as an additional parameter with the actual request, minus the API Access Secret. When the Server successfully rebuilds the signature from the provided values plus the local API Access Secret, then Server knows the client had the correct secret and that the request had not been tampered with.  

  

The new v3 endpoints are authorized for use by providing a valid "bearer token" with requests. To generate the token, you'll need two values- Client ID (aka "API Access Key") and Client Secret (aka "API Access Secret")- which get concatenated together separated by a colon, Base64 encoded, prepended with "Basic " and then posted to the /webapi/oauth2/token endpoint in an "Authorization" header. An "access token" is provided in response, and that token can then be used as the Authorization header value (prepended with "Bearer ") in subsequent calls to any of the other v3 endpoints. The token lives for a total, non-configurable time of one hour, after which time a new token will need to be generated. 

  

  

V1 API 

V2 API 

V3 API 

Transport 

http/https 

http/https 

http/https 

Authorization framework 

OAuth 1.0a, OAuth 2.0* 

OAuth 1.0a, OAuth 2.0* 

OAuth 2.0 

Session management 

stateless 

stateless 

1-hr bearer token 

Signed request 

yes 

yes 

no 

Focus 

Workflow Execution 

Oversight 

Content Administration 

Total Endpoints 

22 

8 

58 

 * OAuth 2.0 available with v1 and v2 when using new “/webapi/” path instead of original “/api/” path 

  

Use Cases 

 

Because these endpoints are focused on content administration, their availability opens up a wide range of possible uses, including: 

  • Migrating content from one Server environment to another 
  • Automated deployment of workflows from a centralized version control repository 
  • On SAML-configured Server's, more granular definition and authorization control  

 

Note that not all content can be directly migrated from environment to another as some concepts such as Gallery shared Data Connections are designed to be environment-specific. 

 

Getting Started with v3 API Endpoints 

 

Alteryx Server comes with the interactive documentation for the API by default. In v21.4, the v3 Swagger documentation will reside at [WEB API ADDRESS]/swagger/ui/index]. This will allow you to see the required parameters for each endpoint, actually issue requests, and see the responses. Note that the base API address is configurable via System Settings with Server v21.4. 

 

Introducing the v3 API Macro Pack 

 

There are obviously many possible ways to call API endpoints, including Alteryx workflows. We've built a macro pack to easily interact with these new v3 endpoints. Having Alteryx tooling available for Server API interactions allows for fast and flexible integrations. The pack consists of five macros:  

 

     DanH_0-1644017699992.png   GET Macro - used for reading records 

     DanH_1-1644017699993.png   POST Macro - used for updating records 

     DanH_2-1644017699994.png   CREATE Macro - used for adding new records 

     DanH_3-1644017699994.png   DELETE Macro - used for deleting or disabling records 

     DanH_4-1644017699995.png    AUTHENTICATE Macro - used to generate a token which can be reused in multiple requests for 3599 seconds from the time issued

 

Installing the v3 API Macro Pack  

 

The YXI installer for the Macro Pack is included below. The Macro Pack uses the new v3 API endpoints, which are available starting in Alteryx Server 2021.4. To use the macros, you will also need to be running Alteryx Designer 2021.4.  

 

When installing the Macro Pack using the YXI, you can install it for the executing user, or for all users on the machine (requires Admin privileges). When installing the Macro Pack in an Alteryx Server environment, you must install the YXI for all users by running Alteryx Designer as an administrator. 

 

Using the v3 API Macro Pack 

 

After installing the macros on a machine with Alteryx Designer, a new tool folder should appear in your Designer called “Server v3 API". Before using the macros, consult the interactive Swagger documentation to understand the parameters that the desired endpoint requires or accepts. The macros allow you to choose an endpoint via the "Action" tab, and that selection then influences what fields are accepted/required for successful execution. For example, the endpoint CREATE /v3/collections/ requires a field called "contract" as a JSON object, so a field called contract with the properly formatted JSON object must be fed to the macro input. 

 

The macros accepting inputs all require a unique "RecordID" field be included with each record, and can easily be generated with the Record ID tool. The macros accepting inputs also expect three fields which are generated by the AUTHENTICATE macro:  "baseURL", "Authorization Token", and "Base64 Key+Secret", all of which should map automatically from the output of the AUTHENTICATE macro. If you intend to send multiple records into a given macro for multiple API calls, group by the unique "RecordID" field in the "Group By" tab. Lastly, you'll note that each of the four action macros provide success and failure outputs. Receiving failure records should allow you to perform validation and exception handling and/or reporting.  

 

A simple process to create a new Collection would look like this: 

DanH_5-1644017699996.png

 

These macros are designed for use with Alteryx Server v3 Gallery API endpoints and validated on Server version 21.4. The macro pack is provided as-is, without warranty. This macro pack is not a part of the base Alteryx Server product. Use of this macro should always be tested thoroughly in a non-Production environment to your satisfaction. 

  

Frequently Asked Questions 

 

  • If I experience any issues with the V3 API macro pack, will Alteryx Support be able to assist me? 
    • The V3 API Macro pack is not an official Alteryx product offering and is provided as-is, without warranty, through the community as a field-developed solution. If you experience any issues, please leave a comment below. 
  • I already have an integration built on v1 and/or v2 endpoints. Will upgrade to v21.4 break those endpoints? 
    • No, v1 and v2 endpoints will continue to function as they have until they are deprecated, which is estimated to be two full releases after the v3 endpoints support all use cases served by v1 and v2. 
  • Can I build an application with a mix of v1 and new v3 endpoints? 
    • Yes, just note that the authentication and authorization frameworks are different, so you'll need to code your custom application accordingly. 
  • Can I configure the v3 bearer token timeout? 
    • No, this duration is currently not configurable, and lives for 3599 seconds (one hour). 
  • Can v3 results be paginated? 
    • V3 endpoints rely on a combination of filtering options and a verbosity parameter in place of the paging concept present in v1/v2  
  • Is sensitive data encrypted in the requests and responses? 
    • None of the three versions of the API offer a native encryption method. Encryption of traffic should be configured by installing a TLS certificate on the Server, which is considered standard practice. 
  • Can v3 endpoints perform all the same functions as v1 and v2 endpoints? 
    • As of Server v21.4, no. Some functions exist in more than one API version. V3 offers many new functions that are not available in v1 or v2. One notable function available in v1/v2 and not yet in v3 is the workflow execution function.  
  • How do I know what fields need to be fed into any of the macros?
    • You select an endpoint within the "Action" tab of the given macro. The documentation for the endpoint, including required and optional fields, should be reviewed in the API Documentation that comes installed with the Server. Some fields for some endpoints are required to be JSON format, in which case the format specified in the documentation should be used. 

 

Comments
patrick_digan
17 - Castor
17 - Castor

@DanH Great write-up, I'm excited to try out the new v3 API!

Thableaus
17 - Castor
17 - Castor

This is awesome. I'll see if I can find some time to test it

chvizda
8 - Asteroid

Hi all

I currently use the "Subscription" Endpoints of the "old" API capabilities.
Will they also migrated to the new V3 in near future ?

 

I saw only this message:

The V1/V2 API endpoints will be deprecated two releases after all use cases have been supported in the new V3 API.
We recommend writing all new scripts using the V3 API whenever possible.

 

Currently I'm writing new scripts, and I don't want to do it again in the near future.

 

Many thanks

 

Steffen 

Sebastiaandb
12 - Quasar

Like @chvizda we're currently using the "subscription" endpoint with the subscription key and secret to do post/get calls. However, within the new webapi interface i do find V1,V2 and V3 but it only let's me authenticate with my "API access key" and "API access secret", the subscription key and secret are not allowed and thereby i'm not able to post/get any workflow that i have in my private studio. 

 

Does anyone here have a clue were they integrated the api functionality for subscriptions? 

 

Thanks

 

Seb, 

JohnPelletier
Alteryx
Alteryx

Hey folks, a few points to help clear things up on this thread:

 

  • V1, V2 and subscription API endpoints can all work with the user API key and secret now. No subscription key and secret are necessary going forward.
  • You should still be able to access any workflow from your private studio with your user key and secret. If you're having trouble with that, please open a support ticket and let's get that fixed for you.
  • V1, V2 and subscription API endpoints will continue to be around for a while. The message was intending to say that once we had fully replaced all of those endpoints with new V3 versions of them, we would later deprecate them and consolidate all APIs to just one version, but getting all of the V1, V2, and subscription API endpoints re-designed for V3 is not planned for at least a year.
JohnPelletier
Alteryx
Alteryx

Also, a heads up for 2022.1 (our next release in May 2022).

 

We will be deprecating OAuth1 in Server v2022.1, so the migration to OAuth2 for your scripts is certainly coming to your future.

 

We hope this isn't a big deal, since it involves just an update to the base URL (typically from /gallery/api/ to /webapi/) and a change to the auth type (OAuth1 to OAuth2).  All the endpoints' parameters and responses should be identical, with the exception of the GET /workflows/id/package call, which will now return an actual file in the OAuth2 version where it used to return a binary BLOB.

 

If you find this extra challenging, please let us know how we can make it better and we'll do our best.

LisaL
Alteryx
Alteryx

@Sebastiaandb 
There is a known issue (original ID GCSE-440, also listed as TGAL-6414 for reference in future Release Notes) keeping Artisans and Viewers from using the v1 Subscription endpoints with OAuth2.  There are two workarounds until this is fixed in a future release.

  1. Use the older, OAuth1 interface a bit longer.
  2. Work with the Gallery Administrator/Curator to have them make those API calls or elevate you to Curator level if access must be OAuth2.
Sebastiaandb
12 - Quasar

Thanks @LisaL ,

 

We notified our account manager 2 weeks ago about this (he's a great guy by the way ;-)).

Thanks for the workarounds but as OAuth1 will be depreciated in 2022.1 we will most likely just not upgrade until this is fixed. We are keen on changing all our back-end processes to the new OAuth2 standard (as we execute a lot via the api interface) but it needs to be usable by Artisans that are now utilizing the V1 subscription. 

Again, thanks for your reply, i appreciate it! 

 

Greetings,


Seb 

cAral
7 - Meteor

Thank you for sharing this @DanH!

 

Are you familiar with any additional documentation on the PUT /v3/workflows/{workflowID} endpoint? I've tried using it here in python to change a workflow owner (or even more simply, the workflow name) but keep running into a 400 error which I was able to replicate using these tools.

 

cAral_0-1651626269530.png

 

ITTeam
6 - Meteoroid

Any ideas on how to fix this issue with the V3 api? Can connect to the public URL but then receive this error, and the API options will not load: 

Can't read from server. It may not have the appropriate access-control-origin settings.

Is this an Alteryx Systems Settings problem or something that we'd need to get resolved on the LB side (we are running Gallery through an AWS ELB, it worked fine until we upgraded to the latest Alteryx version and are trying to test the V3 api). Thanks. 

levell_x_dunn
10 - Fireball

HI @DanH,

 

I was very excited to see all that was exposed on V3. Especially the ability to now help customers create a collection, add users and add workflows and schedules all through the API.

 

My team gets requests to add 30/40 workflows for these clients, then help other clients, and allowing to remove the manual work to now build into a few workflow templates looks really cool.

 

Unfortunately, I was testing this out as the Alteryx admin and came across a 403 error where I am being denied access to add a workflow or schedule to a collection.

I understand this not working for some people, as you don't want someone "stealing" a workflow but as admin support.. this baffles me 

 

Please see screenshot below

 

levell_x_dunn_1-1653162915252.png

 

DanH
Moderator
Moderator

@ITTeam  It sounds like it could be an issue with headers, though I'm not sure why a different version would behave differently in that regard. The HTTP headers provided by Server can be customized via  a config file at [INSTALL DRIVE]\Program Files\Alteryx\bin\server\config\alteryx.config. Within that file, there's a section httpHeaders , and any additions will be served with requests after restart.

ITTeam
6 - Meteoroid

Hi DanH! Thanks for your reply and for the location of the config file to alter the httpheaders. Will give this a shot. 

-Jonathan 

mchamlee
6 - Meteoroid

Trying to work with the V3 endpoints after upgrading to 2021.4 recently. Porting over custom Python classes/methods from V1, in particular the Publishing endpoint. Receiving 415 Unsupported Media Type with my V3 logic, and confirmed the same response when using the Alteryx provided Postman collection. Any tips/insight into troubleshooting this? I'm using a yxzp that I can publish fine with the V1 endpoint against 2021.4, so fairly certain it's not the yxzp itself.

JohnPelletier
Alteryx
Alteryx

Is it one endpoint in particular that is causing this problem? What kind of response does your code currently expect?

mchamlee
6 - Meteoroid

@JohnPelletier First, apologies for the late reply. I don't appear to get community (or support) update emails anymore, started some months back.

 

This is just impacting one v3 endpoint so far, workflow publishing (/v3/workflows POST). The logic expects status 200, application/json response with the published Workflow id, but as I said this same issue also occurs in Postman which is generally uninterested in the code returned no matter what it is (left up to the user/tester to decide), it's 415 regardless of the tool/technology for me.

JohnPelletier
Alteryx
Alteryx

@mchamlee You should probably file a defect. If it's just a file format or environmental issue, the support team will sort it out, and if it's a legit defect, that's the best channel to get it fixed. 

 

Have any other readers here seen this problem?

LisaL
Alteryx
Alteryx

@mchamlee 
I'm not sure I agree with @JohnPelletier  about one aspect of his recommendation:
If you have a paid license, you can absolutely open a case with Support to get assistance.  The part I don't agree with is the conclusion that this might be a defect/bug.  I think there may be more troubleshooting you can do before concluding that it's a defect.

You might already have done this, but please verify that you can upload using the Swagger test portal.  <yourURL>/webapi//swagger/ui/index#!/Workflows/Workflows_CreateWorkflow after entering your Admin Key and Secret at the exclamation point.

This might help you troubleshoot.This might help you troubleshoot.