Guide to Creating Your Own Connector - User Interface

[RithiS]

This article is part of the “Guide to Creating Your Own Connector” series.

Before reviewing this section, we recommend watching our video on Standard Macros. In this section we will explain how to turn your working connector workflow into an Alteryx macro so it can be used as a tool within other workflows. The Interface tools will let you control which parameters and inputs can be enteredinto the connector macro. Interface tools take user inputs to update other tools inside the macro. For example, the user can enter their own security credentials for a specific API, which will then update tools like Text Input, Download, and Formula inside the macro.

Since there are many dynamic parameters, the Text Box tool is a great choice for user inputs. The Text Box tool lets the user enter values for URLs, client IDs, and any other parameter. It also has a Mask Text option that will encrypt the user's password. The configuration is simple as shown below.

1. Enter the parameter name as the text you want displayed, which identifies it for the user.
   • The other values are not required but may be changed as needed.
     
2. To utilize the user input data correctly, we must use the Action tool. The Action tool is vital because it will take the user input and pass it to downstream tools.
3. The Interface tool will connect to the top left anchor of the Action tool. In our case we are connecting the Text Box tool to the Action tool, which will then connect to the top lightning anchor of the Text Input tool.
   • This flow shows the Action tool taking data input from the Text Box tool and updating data inside the Text Input tool.
     

Configuration of the Action tool will determine what is being updated in downstream tools. Selecting an action type lets you decide what is going to change inside downstream tools. Action types allow specific cells and values to be replaced by user inputs. User inputs can be directly entered into downstream tools or used as part of a formula.

1. We will take the user input from the Text Box tool for URL and then update a cell inside the Text Input tool.
• The Text Inputtoolis configured as so:
  
2. The value __url__ is simply a placeholder that will be replaced by the Action tool.
   • To update the placeholder __url__ we can configure the Action tool as so:
     
3. We know that the cell location will not change so we can precisely identify the cell to update by row and column. Explore the other action types to configure your connector based on its needs.

The three tools are now connected and configured. How the flow works:

1. When the user inputs the URL into the text box, the Action tool will take the URL value and override the __url__ placeholder inside the Text Input tool.
2. The Text Input tool can be connected to a Formula tool. The Formula tool will let you concatenate the URL with a static section or do anything else you desire.
3. Then the newly generated URL can be passed into the Download tool.
   
   
   

To ensure that entered values are acceptable for the API, the Error Message tool can be used. This tool will warn users about missing fields or incorrect values being entered.

1. Error Message is connected to the Interface tool used.
   
2. The configuration requires an expression, which when evaluates as true will display an error message.
3. The expression IsEmpty([#1]) is checking if the #1 wire connected from Text Box to Error Message is empty. If it is empty, it will evaluate to true and trigger the error message “URL is required” advising the user the value is missing.
   

There is a layout view of the user interface called Interface Designer. We recommend having this view open while building the interface. The Interface Designer lets you design the layout by ordering and grouping fields, add labels and links, and test and debug the menu. Become familiar with this section to help improve your macro while building it.

You can debug the macro as so:

1. The wand button on the left above is the test view. This lets you test input validation and view data passed through the Action tools.
2. Test values can be entered into the test interface and then debugged by clicking Open Debug on the right-side menu of test view.
• Right-side Menu of Test View
  
3. Open Debug opens a duplicated workflow in a new tab with three debugged sections: Original File Name, App Values, and Actions Log. It shows where the test values pass to as if the actual macro was ran. This can help you understand if the Action tools are configured to update the correct cells or values.

After your connector macro is mostly complete, a Macro Output tool should be added at the end. Macro Output will let the user output the data to their preferred output for usage.

1. If the workflow is ready to be used as a macro, save it as a .yxmc file.
2. Go to the Workflow Configuration and click on the Workflow tab.
3. Under Type, select Macro and save as a Standard Macro. You can save other types like batch or iterative, which you can read about here.
   

Now that your connector is complete, there are two ways it can be loaded into a workflow:

1. Right-click inside a workflow and select Insert. At the bottom of the list is Macro..., which you can select and browse for the macro.
   
2. You can add macros to your tool palette by creating a macro repository. The repository is a specified directory that Alteryx will look in for macros to add.
   1. To configure a directory, go to Options > User Settings > Edit User Settings.
   2. Click on the Macros tab.
   3. Then click on the circled plus on the right to add your repository. Additional information on using macros in workflows can be found here.

[Drader98]

That's great....! Seamless and efficient - thanks for putting in the effort to document that.