Community Spring Cleaning week is here! Join your fellow Maveryx in digging through your old posts and marking comments on them as solved. Learn more here!

Alteryx Designer Desktop Knowledge Base

Definitive answers from Designer Desktop experts.

Guide to Creating Your Own Connector Series

TashaA
Alteryx Alumni (Retired)
Created

Alteryx provides many built-in data connectors and there are additional ones available for download from the Gallery. This list currently includes tools such as Google Sheets, Salesforce, Marketo , and others. If you require a connection to an API or web service that Alteryx does not already provide a tool for, this knowledge base article will serve as a reference guide for you to build a connector using Alteryx. This series will focus on utilizing Alteryxmacros to build a tool that is a connector to a datasource, so these terms will be used interchangably throught the guide.

 

When working with a new API or web service, breaking the documentation down into a digestible format can be difficult. A good way to get started is to look at the required authentication method for the API and determine if the method can be implemented in Alteryx. A more detailed view of authentication in Alteryx can be viewed here.

 

Once you have determined the method of authentication needed by the service, and implemented the process to authorize, the next step is to generate and execute the actual request to the service. Examine the available endpoints that the API provides, and try to answer the following questions:

 

  1. What data can I access with this API?
  2. Will I need the response of one API request to construct the request for a subsequent API request?
  3. Will I be sending data to the service for upload (a POST request) or do I simply want to download information from this service (a GET request)?

The answers to these questions can be used to lay out the flow of the next section of your macro. More information on constructing the request can be seen here.

 

To build a robust connector, it is most likely desirable to parse the response that was received as a result of your request. This includes sending and downloading data. If you were attempting to upload data, it is good to read the response so that you know if your request was received and valid, and provide this information to the user of your connector. If the connector is built for downloading data, you will want to output a nicely parsed table of data. A detailed explanation of parsing the API response is here.

 

While interacting with an API, you will receive error messages from time to time. The ability to handle these errors and stop processing, as well as alert the user to the issue that was encountered, are additions you can make to your connector that will make using it a more seamless experience.Read more on error handling here.

 

Once you have a workflow constructed that handles authentication, executes the API request, and parses the output data, you can turn the workflow into a reusable macro. This includes creating the macro interface that updates the options that you want parameterized as part of your connector. More about designing the macro interface can be read here.

Quick links to the guides in the series:

 

Guide to Creating Your Own Connector - Authentication

 

Guide to Creating Your Own Connector - Generating the Request

 

Guide to Creating Your Own Connector - Parsing API Response

 

Guide to Creating Your Own Connector - Handling Errors

 

Guide to Creating Your Own Connector - User Interface


Let us know what other information you want to know about building data connectors in Alteryx, or if you have built any connectors and have tips and tricks to share!



Comments
TR
8 - Asteroid

Hi @TashaA, enjoyed your presentation about building connectors during Inspire 2017 and it was a pleasure meeting you. As I mentioned I've been working on building a custom connector following this series. The example you used during the presentation was in macro format reading in variables from a text input. I've been able to replicate an issue where the action tool will not read more than 20 variables (20 columns). When you add the 21st column/variable the column dropdown in the action tool no longer populates with the column and the variable. It just shows a column count. I can provide further details but can you replicate and confirm this? In the meantime I'm going to add another text input to handle my 21+ additional attributes and then append the two text inputs to provide a workaround. Let me know if you can replicate this and I can provide additional documentation if necessary. Thanks again!

Regards,

Todd 

TashaA
Alteryx Alumni (Retired)

Hello @TR, it was very nice to meet you in Vegas as well. 

 

I apologize for the delayed response, the notification slipped by me! 

 

Do you have a workflow that shows this behavior? 

 

TR
8 - Asteroid

Hey @TashaA thanks for catching up. I've worked around this issue months ago... but can revisit this and see if I can send you a replicated workflow. The connector is still in development so I may ping you with future questions ;)

 

Thanks,

Todd

 

AndrewDK
6 - Meteoroid

Hi I'm trying to access the Quintly API using basic auth. I can connect via a browser and Postman but I keep getting "Auth failed" when I use the download tool in Alteryx. I've tried the username and password on the connection tab, adding "Authorization" and "Basic <base64 encoded username:pass>" in the headers. Nothing works, I'm at my wit's end. Has anyone had this issue with basic auth?

TashaA
Alteryx Alumni (Retired)

Hey @AndrewDK!

 

That is really frustrating, I totally understand. You are definitely on the right track with the Authorization header. 

 

I would say to try a few things: 

 

  1. Try checking or unchecking encode url option on tab 1 of the Download Tool, sometimes if this is checked it will encode your already encoded base64 value for the header and then the service can't decode it 
  2. Make absolute sure that your value of the Authorization header is Basic[space]Base64encoded username/password (with no extra spaces at the end)
  3. Install Fiddler to compare the outgoing network traffic between a Postman request and the request you are generating through Alteryx

Let me know how it goes!

AndrewDK
6 - Meteoroid

Thanks @TashaA,

For #1 I tried the encode URL toggle (don't need encoding), no dice.

For #2, I copied the exact same URL and header text from the Alteryx Fiddler output into Postman and it works fine (minded the spaces as well).

For #3, I'm not sure what Fiddler is telling me; the requests look very similar except the Alteryx one doesn't have User-Agent in the request header and cache-control, cookie, and Connection are in the return header, not the request. However, even when I specify a user agent in the request it still fails.

Does this suggest anything to you?

Thanks!

 

The Postman request:

GET <url> HTTP/1.1
cache-control: no-cache
Postman-Token: <tokenstuff>
Authorization: Basic <client:pass>
User-Agent: PostmanRuntime/7.4.0
Accept: */*
Host: api.quintly.com
cookie: <cookie stuff>; <cookie stuff>
accept-encoding: gzip, deflate
Connection: close

 

HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 30 Nov 2018 16:20:48 GMT
Server: Apache/2.4.10 (Debian)
Content-Length: 1902
Cache-Control: no-cache, proxy-revalidate
Connection: close
Age: 0

 

The Alteryx request:

GET <url> HTTP/1.1
Host: api.quintly.com
Accept: */*
Accept-Encoding: deflate, gzip
Authorization: Basic <client:pass>

 

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Date: Fri, 30 Nov 2018 16:21:24 GMT
Server: Apache/2.4.10 (Debian)
WWW-Authenticate: Basic realm="Login"
Content-Length: 79
Cache-Control: no-cache, proxy-revalidate
Proxy-Connection: Keep-Alive
Connection: Keep-Alive
Set-Cookie: <cookie stuff>; Path=/
Proxy-support: Session-based-authentication
Age: 0

AndrewDK
6 - Meteoroid

Alright, I think I figured out what is happening, my proxy service is using BSCI cookies. Chrome and Postman both accept these cookies and attach them to the request header but Alteryx does not. This results in the proxy stripping the auth headers before sending to the API service resulting in failed auth. I have no clue why this is happening but is there a way for Alteryx to accept these cookies from the proxy service? I can manually add the cookies to the header and the request succeeds but I don't know how often the cookie values change.

 

Here is a quick link re BSCI cookies: https://webmasters.stackexchange.com/questions/32931/what-is-the-bcsi-cs-cookie-for

 

Thanks!

davidhenington
10 - Fireball

When will the Download Tool support curl insecure code for URL's with bad certificates? 

davidhenington
10 - Fireball

what to do when attempting post request/upload and you get no response other than the http string that seems to indicate connection denied? 

npandya
7 - Meteor

Hello,

 

I am getting Error: Download (3): Error transferring data: SSL peer certificate or SSH remote key was not OK while trying use download tool to get the API key by POST.

 

I can get the key in cmd with curl insecure and I used the same command in Run Command tool but it's still the same error. I don't know how to use curl --insecure with download.

 

Please guide.

Shifty
12 - Quasar

How have I only just found this now?