Alteryx Server Knowledge Base

BrianR · ‎12-23-2020

How to Format Analytic App responses in json via Interactive API

When using the Interactive API page of Alteryx Server, you can test out various responses to pre-defined Interface controls in your Analytic Application. Formatting the json text requires very specific text - this article will share some examples on how to enter the information correctly. Attached is a sample Analytic Application that can be used to reference the examples in this article.

Prerequisites

Alteryx Server
- All
Alteryx Server Private Studio API Key and Shared Secret
- Information below on where to obtain these keys

Procedure

Obtain your API Keys

1. Log on to your company's Gallery, and locate your Account's API Key and Shared Secret Key, which can be found in your Account Settings section of the main Gallery page

Hover over your name in upper-right portion of Gallery, and click My Profile
Click the Keys tab, and under Private Studio API, copy both your Key and Secret (un-mask Secret to see it)

2. Access your Alteryx Server API Interactive Documentation page

By default, this will be your Alteryx Server Gallery URL, plus the link to /api-docs - such as http://<servername>/gallery/api-docs
Under the Subscription tab, paste in both the API Key and Shared Secret into the boxes at the top of the page

3. Now you can access the workflows in your Subscription, and also get some important information - the id of any workflow / Analytic Application.

For this example, you should choose one that is configured as an Analytic App, which at least one type of Interface tool. For an example workflow, see the attached application below for testing purposes. Should you choose to use this one, you have to first save it to your Private Studio.

Calling your first API

1. The first API we need to call is called the the workflows/subscription API Endpoint.

Click /v1/workflows/subscription/ to expand, and scroll down to locate the "Try it out!" button (it may be greyed out, but it will still work). Click that button - and if all is configured correctly, the Response Body section will list all your workflows and applications that are stored in your Private Studio.
Make note of the id field, and copy that for later - you will need this several times as you go through the various API Endpoints.

2. The next endpoint will enumerate all the questions (configured Interface tools) in your App.

Click /v1/workflows/{appId}/questions/ to expand, and paste in the appId you copied earlier. Next, click the Try it out! button.
In the Response Body, you will see a list of your questions (your Interface controls), along with some important info you will need for the next step.
You will see a series of names and values for your various Interface controls - the important parts of this are the name key and its value. In the example below, one name is "NumericUpDown_Sales", and the value is "15000". This is coming straight from your Application, which you can change for your controls by clicking the desired Interface control, then clicking the Annotation button within the Configuration window.

3. Now it's the fun part, actually running our Analytic Application via the Alteryx Server API, and entering custom parameter values.

To start this process, click the /v1/workflows/{appId}/jobs/ section to expand it, and enter in your appId from earlier.
Next, in the values section, this is where we will get to the main subject of this article - how to format the json to accurately pass along values to our Analytic App.

Formatting your values

1. To the right of the values box, notice there's a yellow box with some formatted json text. It has empty placeholders in the correct format.

Click on that yellow box to populate this into the values box, or you can start from scratch, either way should work fine. The example below shows the general format of the json to be populated, and what gets populated in the values box as a placeholder.
For the "name" key, this is where you will insert the name of your first Interface control. Using the example from above, I will enter NumericUpDown_Sales within quotations. For example:

{
  "questions": [
    {
      "name": "NumericUpDown_Sales",
      "value": "16000"
...

Note that I decided to use 16000 instead of the default 15000...this should run my App using this newly entered value.
If you have only one Interface control, you're almost done - you do have to set a priority value - note the "priority": "1".
The finished json, for a single question Numeric Up Down control will look like this:

{
  "questions": [
    {
      "name": "NumericUpDown_Sales",
      "value": "16000"
    }
  ],
  "priority": "1"
}

Test it by clicking the Try it out! button. If all is well, you will see some information populate the Response Body section, with a status of "Queued"...this means your job is queued for execution by Alteryx Server. If you get an error, that means you most likely formatted something a bit incorrect - we'll get to some detailed examples of various ways to format various interface controls in just a bit.

Did it work?

1. Now for the big test - did it work? To check, you will use yet another endpoint.

Click /v1/workflows/{appId}/jobs/.
Plug in your appId once more, and click the Try it out! button...you will get the result of your jobs that were queued for execution. Here's what the response will look like, in my case, a successful result:

2, Before we get to the various interface formatting references later on in the article, here's a few more things you can do with some additional endpoints.

First, check your job via /v1/jobs/{jobId}/. What this does is allow you to see details about the job that was just ran...you will need your Job ID - which you can get from the results window from /v1/workflows/{appId}/jobs/.
- Plug in your jobId this time, not AppId to see this information.
- Within the Response Body section of the /v1/jobs/{jobId}/ endpoint, you will see a section for outputs...it will look like this:

3. Make note of the id for a given output.

In the example above, the id of the output I would like to explore is 5fda04bba3480000820017ab. We can use the next endpoint to take a look at that output.
Using both the jobId and the outputId, we can test the /v1/jobs/{jobId}/output/{outputId}/ endpoint.

Note the addition to the format box - I asked for csv so I can view the results right in the Response Body section. In my case, the original format of the output was a yxdb file, and while it will show data, in this window, csv formatting will allow you to see the data in a usable format.

Reference - example json for various Interface controls

Shown below are various examples of how you can format your Interface controls.

List Box
Sample json:
    {
      "name": "ListBox_Segment",
      "value": "('Consumer','Small Business')"
    },

Notes

The "name" refers to the actual name of the control in your application - this will be true for all the remaining examples below
The "value" for a List Box is a comma-delimited list, within parentheses, and the individual values wrapped in single quotes ( ' )

Numeric Up Down
Sample json:
    {
      "name": "NumericUpDown_Sales",
      "value": "20000"
    },

Notes

The numeric value is wrapped in double-quotations

Drop Down
Sample json:
    {
      "name": "DropDown_City",
      "value": "Denver"
    },

Notes

The single-value drop down control, will hold its single value within double-quotations.

Text Box
Sample json:
    {
      "name": "TextBox_Growth",
      "value": "1.2"
    },

Notes

The value (numbers, text, etc.) will be listed within double-quotations.

Radio Button
Sample json:
    {
      "name": "RadioButton_C",
      "value": "True"
    },

Notes

The values of either True or False will be entered into double-quotations.

Date
Sample json:
    {
      "name": "Date_OrderDate",
      "value": "2020-12-15"
    },

Notes

The date value should be entered in the standard Alteryx date format (yyyy-mm-dd) within double-quotations.

An example of all the controls above together, in a completely formatted json example

{
  "questions": [
    {
      "name": "ListBox_Segment",
      "value": "('Consumer','Small Business')"
    },
    {
      "name": "NumericUpDown_Sales",
      "value": "20000"
    },
    {
      "name": "DropDown_City",
      "value": "Denver"
    },
    {
      "name": "TextBox_Growth",
      "value": "1.2"
    },
    {
      "name": "RadioButton_C",
      "value": "True"
    },
    {
      "name": "RadioButton_N",
      "value": "False"
    },
    {
      "name": "Date_OrderDate",
      "value": "2020-12-15"
    }
  ],
  "priority": "1"
}

Notes

Note that each question is surrounded by brackets { }, and if there are more questions, each of them has to be separated by a comma between values. That's why the last question (Date_OrderDate) does not have a comma at the end, it's the last question in the string of questions.

Common Issues

I can't find my API key for my Subscription
It could be that your Alteryx Curator has not granted API access for your Subscription. If you click My Profile, then access the Keys menu and you don't see any API keys, this is most likely the reason. In summary, you will see that your Subscription has to have API enabled to be able to use the Private Studio API. Further, there are various levels of API Access, which grant access to different API's in addition to what's mentioned in this article. Consult the links below in the Additional Resources section for more information.

These formats don't work with my Analytic App
The most common error - make sure you test your Analytic Application before working with the API Interactive documentation...it will be much easier to troubleshoot a faulty application before you start formatting your json to test. Specifically, make sure you test all your Interface controls with values that return a result. Make note of those values to replicate in the Interactive API page.

Other errors will typically be incorrect formatting, such as a misplaced comma, an extra comma and the end of your string of questions, not including single-quotes to delineate individual vales in a List Box, etc.

Additional Resources

Alteryx Server Knowledge Base

Formatting Analytic App responses in json through Alteryx Server's Interactive API