New Box Connectors on the Alteryx Public Gallery

[AndrewKramer]

Editor's note: As of August 11, 2021, the Box Connector tools have been substantially updated. The most up-to-date documentation for these tools is available here:

• Box Input Tool 
• Box Output Tool

After several years as one of the top ideas on Community, I’m happy to announce the public beta of the Box Connector in the Public Gallery! Looking to get up and running? This is the post for you!

First of all, why a Box Connector? For many years, Alteryx Customers have been using Box Sync to interact with their Box Data. While this solution works, it is less than ideal since it requires mirroring data locally, and configuration issues arise when migrating workflows to Alteryx Server.

To get around these difficulties, Box provides a robust set of APIs for developers to build on top of. This allows users to interact with their box account, upload files, download files and more with ease.

The use of APIs requires setting up an Application in the Developer Console, meaning that you can’t simply sign in using your organization’s SSO credentials. Typically, you are best to partner with your Box administration team to ensure proper setup and access to your files.

Since the Box Tools upload and download files to Box, you will want your administrator to create an Enterprise Application:

Next, you will have to choose your authentication method, either Standard OAuth 2.0 or OAuth 2.0 with JWT. Both options have pros and cons as described below:

1. Standard OAuth 2.0:

1. Manually authenticate via standard OAuth
2. Authenticate as yourself
3. Access expires after 1 hour (must re-authenticate)
4. Not supported on Alteryx Server

2. OAuth 2.0 with JWT:

1. Automatically authenticate via a .json credentials file
2. Authenticate as a service account
3. Need to store .json in secure location
4. Supported on Alteryx Server with 2020.3

Once your application is created, you can obtain the necessary connection parameters in the Configuration section of the Admin Console.

The tools come as a .yxi file. To install, double click on the .yxi to open it in Designer and click install:

The install process will install two tools that will be available in the Developer tab in the tool palette:

1. Box Input: Reads files from Box into Alteryx

2. Box Output: Writes files from Alteryx to Box

When dragging the Box Input or Box Output tool onto the Canvas, you will be asked to select your authentication method in the Drop Down. Your options are Service-to-Service (OAuth 2.0 with JWT) or End User (Standard OAuth 2.0):

For Service-to-Service, you will be prompted to provide the file path for your .json credentials to authenticate to box. Your JSON Credentials File [redacted] typically looks something like this:

After a successful authentication, your credentials are saved in the workflow XML and encrypted at the machine level:

For End-User, you will be asked to provide several parameters:

If you do not know these parameters, you can look them up in the Configuration section for your Application in the Box Developer Console:

Once authenticated, an interactive file-picker is rendered, allowing you to choose your file. Note that only CSV, JSON, AVRO and Excel are supported.

When uploading a file, you will also have the option to create a new file. Don’t forget to Specify a file extension for your destination file.

Once you select your file, pertinent information, such as File Name and File Id are written to the workflow XML:

When the workflow is run, a Python Process is kicked off to read/write the data from Box. Under the hood, we are using the Box Python SDK to access the specified Box file as defined in your Workflow XML.

For example, the following code downloads your file from Box to Python:

Afterwards, your file is parsed based on your specified delimiter in the UI:

There you have it! You now have brought data from Box into Alteryx that is now available for downstream processing.

Looking to deploy your workflow on server? This functionality is coming in our upcoming 2020.3 release. Both Designer and Server will need to be on 2020.3. A small change to your server configuration will be required, so please reach out to Customer Support when trying to setup the Box Connector on Server.

[SabrinaCB]

Nice!! Thank you Andrew

[WSData_dup_359]

Andrew,

Thank you for this.  I am trying to test it using User Authentication.  The CID and Secret are simple copies from the Box admin screen.

What are we supposed to use for the Redirect URI? (Since Alteryx is receiving the authentication info, I am not sure what URL to put there).

If I use the default (app.box.com), when I click next, I get an authorize screen from Box, it then allows me to see my files, but if I close and run,, I get a error

Error: Box Input (2): No access token available. Please authenticate in the UI for End User Authentication

Thanks for any help you can provide.

[WSData_dup_359]

One more question.  If using Input Tool, how do we download multiple files with the same shape?  For example *.XLSX?

[PhilipB]

Hi @WSData_dup_359 

The Box Connector allows one input only. To download multiple files (even with the same shape/schema), you would need to input multiple Box Input connectors.

For the Redirect URI, you can simply put a URL that doesn't have an auto-redirect. I use   https://community.alteryx.com/help

[Dynamomo]

Hi @AndrewKramer ,

I'm trying to understand how this works on server.  So any user wanting to use this connector will need to get a CID and Secret then save their workflow to the gallery.  Is the CID and Secret saved into the workflow so basically the workflow is always using the workflow developer's credentials?  

[AndrewKramer]

Hi @Dynamomo, the credentials are encrypted and stored in the Alteryx workflow. Note that for the Box Connector to work on Server, you will need 2020.3 for Designer and Server. There are a few additional server configurations required that support can help with.

[Dynamomo]

@AndrewKramer  - Thanks for your timely response.  Much appreciated!

[nboyde]

Hi @AndrewKramer ,

I seem to be having a similar issue to @WSData_dup_359. I followed your instructions above closely so not sure what I am missing. I am able to authenticate my connection with box (end user) but rather than an "interactive file picker" rendering, I see an Alteryx pop up window that allows me to see my box files just like a normal web browser. But I am unable to select what files to use. I exit out of the browser pop up and when I run the WF I get the error WSData mentioned: "Error: Box Input (2): No access token available. Please authenticate in the UI for End User Authentication". I have tried using both the following URL's for "redirect URI"  https://community.alteryx.com/help and http://app.box.com

Any insights or help from anyone would be much appreciated! Thank you!

Point of instructions that I can't get passed:

"Once authenticated, an interactive file-picker is rendered, allowing you to choose your file. Note that only CSV, JSON, AVRO and Excel are supported."

Interactive file picker I believe I should be seeing but am not:

Alteryx pop up I am seeing after hitting next:

Thank you!

[lepome]

@nboyde 

I set this up successfully.  Here are some of the things that appear different since Andrew wrote the article.

Initially, I was unclear as to how to find the pages on which to set up the Box side of the interface, but it all happens in the Dev Console.
Initially when I log into Box as a user

The Dev Console looks different when I do it than when Andrew wrote the article, so I selected Custom App.

Click on the icon for Custom App

That brings up the pop-up where you select the authentication type you want.  I see that you're using the Standard OAuth 2.0, so we'll continue with that.
Select User Auth and give your app a name

Once you've created the app, you can set up some of the parameters:  I followed the recommendation above about the URI, so I had this...

I wanted to set this up for Box Input as well as for Box Output, so I specified Write

And here is the part I think you might need to modify to make yours work....  Make sure the box for Make API calls using the as-user header is checked.  I also specified that requests from my URL should be accepted.

Make API calls using the as-user header

I then saved my changes, and copied the Client ID and Client Secret from higher up on the page, and pasted them, together with the URI, into the respective boxes of the Box Input tool configuration screen.

Configure the Box Input Tool

I still had to authenticate with my own credentials and Grant access to Box
Log in (Authorize)Grant access to Box

But after that, the next page of the tool configuration appeared as desired.

Click Select if necessary

There I was able to click on the expand arrow >  to see the file structure and select the file I wanted to bring into Alteryx.

Show file tree and choose the desired file.

All that was left then was to run it to make sure it worked.  (It did.)

[lepome]

@nboyde and anyone else who is interested

The above explains how to configure on the Box side of things for End User authentication (OAuth 2.0 User Authentication).  This section is relevant to Service-to-Service authentication (OAuth 2.0 with JWT).

In order to configure this way, you must enable 2-factor authentication.  This is done from the Account Settings page.  Click on your logo in the upper right of the initial screen and select Account Settings from the drop down.

To get to the page where you can enable 2-factor authentication

Then scroll down until you find the section on 2-Step Verification, more than halfway down:

Choose a third-party authentication app. Here I've used Microsoft's, but whatever your company uses will probably work.

Now you're ready to set up the app.  Just as before, start in the Dev Console:
Open the Dev Console

And again, select Custom App by clicking on the icon.

Click on Custom App's Icon

This time, however, select the top option, Server Authentication (With JWT) and then enter a name for the app:

Select Server Auth and enter a name for the app

Enter info on the General Settings page and then move to the Configuration.

Select the appropriate of the two options in App Access Level and if you intend to write to the Box location, make sure to check Write all files and folders stored in Box:  

Each of the Access options will automatically check some of the settings in the next section.

Further down, click on Generate a Public/Private Keypair, and just to be safe, enter your machine name in the CORS Domains section in the Allowed Origins box:

Generate Keypair and enter your computer in the Allowed Origins list.

When you click on Generate Generate a Public/Private Keypair, a JSON file will be created and you'll be prompted to save it somewhere.  The documentation indicates that Box doesn't store this in an accessible form, so if you lose the information in the JSON file, you will never again have access to any files in the new Application section of Box.

Note the mention of the "new Application section."  We'll come back to that a bit later.

When the Application is configured, be sure to click on Save Changes.

Save the app's configuration.

Configure the Webhooks if you enabled them, and finally go to the Authorization tab.  There you must click Review and Approve.

Changes to apps using JWT must be authorized by an administrator.

If you are the Administrator, then the email will go to you.  (The administrator is listed on the General Settings page.)  Once your app has been approved, you'll be able to use it with Alteryx.

The App you created generates its own user account.  This account is initially empty.  This user is only accessible through the Admin Console by default.  The administrator can make changes to this account.  The details of that are out of my scope, but it is important that you know about it.

An example of the new "account" after having added some files.

[lepome]

@nboyde 
Re: End user authentication.  I was incorrect about "Make API calls using the as-user header" being required.  I was able to remove that as long as I had my computer listed in the CORS Domains section in the Allowed Origins box.

[lepome]

@nboyde and others...

As I mentioned in the post above, when you create a Service to Service app, it will create a separate "user" that has no files in the folders initially. 

The Service Account ID is listed in the General Settings of the app you created in Box.eneral Info

You can just use that as you go, but if there are resources you want to use in Designer, you can create a folder and populate it with such shareable resources.  Then share that folder with the "user" that is the Service Account ID that has been created.

Paste in the Service Account ID as the person to share with.

[DmtCoj]

Hi team,

what is a workaround to resolve the following issue? Any tips are highly appreciated.
Thank you in advance.

[nboyde]

Thank you for all your help @lepome !

[lepome]

@DmtCoj 

In the words of the late, great Douglas Adams, Don't Panic!

The error message itself contains the information you need.  But let me explain what I think your situation might be.  

You probably installed your Box tools some time ago.  More recently, you probably upgraded Designer (from a version prior to 2020.4) to 2020.4 or to 2021.1. 

Earlier versions of Alteryx software used Python 3.6 as a platform for many Connectors tools.  The newer versions use Python 3.8, so when you upgraded Designer (or Server) you needed to reinstall those tools that were built in Python.  You can find more information about this in the Help link that is given in the error message.

[davidhenington]

Should the gallery page for this be updated to indicate that it can be used on the Server? 

[Nichole_Rip]

Hi,

We've got an Excel file with the .xlsm extension that are needed as input into a workflow. The file are on a Box drive so I'm using the new Alteryx Box Input connector to access the file. When I choose the "XLSX" file format, I'm able to navigate to and choose the .xlsm file. But the Box Input throws an error "Excel file must be xlsx, not xls". Is there a way to work around this error?

Thank you!

[lepome]

@davidhenington Not at this time. 

These Box connectors described above are the Beta 1.0.x and have not been validated, so are not technically supported for production use. 

Note that there are a completely different pair of connectors that are intended to be released this year.  Those others are also floating around as beta tools, but have the word 'box' on them and are version 2.0.  Those are not currently compatible with any released server versions.

[lepome]

@Nichole_Rip 
I have not observed that, but it doesn't surprise me that .xlsm files don't open this way.  They have more information types built into them than .xlsx files do.

[davidhenington]

Once you've added your box app account as a collaborator in a new box directory, how do you get the Box output to recognize that directory? 

Answer: make sure you're using the right Box app 🙂

we need a delete button! 

[davidhenington]

Update: the issue was due to confusion between apps being used. 

[apathetichell]

Hey @lepome - do you know of any reason why the new Box 2.0 connector (and other browser based authentication/SSO MFA) based authentication would go to a screen saying that Chrome hasn't been updated in 3 years and needs an update (Chrome on the system is up to date)... With posting to private gallery it allows you to skip but the box tool won't go forward. If I disable auto-configure it just hangs on a white box. This is for Box 2.0  using SSO in version 2021.3...

[NeilR]

Note: As of August 11, 2021, the Box Connector tools have been substantially updated. The most up-to-date documentation for these tools is available here:

• Box Input Tool 
• Box Output Tool

[mcha54]

Hi there! On latest Box Connector tool, I'm trying to use JSON Web Token. Anyone know what exactly is the "User Account ID"?

In the Box app configuration, I see User ID, Enterprise ID, Service Account ID, Box User ID.

[milos_bijelic]

Hey @mcha54 , 

You can find your User Account ID by clicking on your profile picture on box.com, then going to account settings. There you can find a section called "Account Details". In there, you will find your User ID, which is the same as your account ID.

Additionally, you should be able to connect to Box using the Box Input Tool and the JWT Authentication Method by leaving the "User Account ID" blank 

[HenryO]

Hello, 

Can someone please tell me how to get the latest Box Input tool to work on the Server?  Everything works fine in my local designer using JWT Auth, but when deploying the workflow to the server the Box input tool fails.  I'm using 2021.4 version of designer and server and the Box Input tool is the latest version 2.4

Thanks,

[riank]

I am also unable to use the Box Input tool on the server. The workflow runs locally using JWT Auth (stored on a shared drive that is definitely accessible from the server / used in other workflows). When attempting to save to the server, there's an error on a Join tool that "Both left and right inputs must have connections." The right input is the only one with errors in the Configuration and the only tool connected to the right input is the Box Input tool. I'm using 2021.4 Designer and the server and my local machine are running Box 2.3. Thanks!

[milos_bijelic]

Hey @HenryO , 

Here is an article showing how to get the Box Connector working on the Server 

Hope this helps! 

[milos_bijelic]

@riank similar to my comment above, try following this guide - How To: Use the Box Tools with the JSON Web Token (JWT) Authentication Method

[riank]

@milos_bijelic Thanks! I've referred to the guide and everything seems to be set up correctly. The workflow runs without errors. However, the Join tool will frequently show the following error in between runs where the right side seems disconnected and the only tool on the right side is the Box Input tool. Since there's an error on the Join tool, I can't upload the workflow and schedule it on the server, which means I have to manually run this workflow daily. 

  

[lepome]

@milos_bijelic 
Two comments that might be relevant:

1. Just because a workflow throws errors on validation does not mean that it hasn't been published to Gallery.  You might be able to run it from there if you have the correct configuration*. 
2. That behavior of not having metadata propagate after python-based tools is common and is not generally a show-stopper because as you note, running the workflow is generally successful.

* The necessary configuration will use the JSON Web Token, I believe, so you will probably have to publish with the JSON file packaged or save it on the server to have it available at runtime.  You can enable Display Asset Management in Properties Window to attach an asset to be packaged.