Controller

Version:
Current
Last modified: September 04, 2020

The controller manages the service settings and delegates work to the workers. You can only enable one machine as the controller in a deployment.

Configure the controller component on the Controller screens in System Settings. The Controller screens are available in System Settings if you've selected 1 of these options on the Environment > Setup Type screen:

  • Designer and Scheduler Only
  • Complete Alteryx Server
  • Custom > Enable Controller

General​​​ Configuration

The General Configuration screen includes configuration options such as where you want to store temporary files and log files and what information you want to log.

Screenshot of the System SettingsController > General screen.

Controller Token

The Controller Token is an auto-generated secret key that the controller uses to communicate with workers and machines using Designer.

If a machine using Designer is not a controller machine and you want to schedule a workflow for a future date, you have to add the controller token on the Schedule Workflow screen to schedule a workflow. 

You will also need the controller token if you want to have one machine act as a controller and another machine to act as a worker. Set up the controller machine to get your controller token. Then, add the controller token in System Settings > Controller > Remote when setting up the worker machine.

You can regenerate the token if necessary, for example, if the token is compromised. Regenerating the token requires updating Gallery or worker nodes in the deployment. If you want to change your token, select Regenerate

Workspace

The Controller Workspace is the location where the controller stores temporary or cache files. By default, the folder is located within the global workspace folder as defined in the Environment screens in System Settings. Use a location that is safe to store large amounts of files.

Logging

The controller produces logs for events, such as services started and shut down, execution requests, etc. These logs can be helpful for troubleshooting. The first field is the storage location for these log files. By default, the location is C:\ProgramData\Alteryx\Service. See Log Files for more info.

  • Level: Choose the messages to log. 
    • None: No logging.
    • Low: Log only emergency, alert, critical, and error messages.
    • Normal: Log low, warning, and notice messages.
    • High: Log all message types.
  • File size: Specify the maximum size of a log file.
  • Enable log file rotation: Log files can become quite large. Enabling log file rotation places max size log files in an archive file and writes logs to a new file. This prevents large log files that are difficult to consume in standard log readers.

Scheduler

Select Enable Scheduler auto-connect to allow users on the machine to auto-connect to the Scheduler. Enable this if you have difficulties connecting to the Scheduler.

Insights

Select Enable Insights to allow the machine to handle requests for rendering insights in the gallery. Insights are interactive dashboards created in Designer.

Engine

Check Enable AMP Engine to enable running workflows that use the Alteryx Multithreaded Processing (AMP) engine in this environment. This is the on-off setting for the Server environment. If you enable the AMP engine for the controller, you also need to set at least 1 worker to run the AMP engine on the System Settings > Engine screen. See Engine documentation.  

Understand AMP Engine Settings

The Enable AMP Engine setting on the System Settings > Controller screen is the on-off setting for the Server environment. This setting enables AMP at the environment level. The setting in System Settings > Engine tells the worker which engines it can use and thus, which workflows it can run.

For example, let's take a 3-node environment. Node 1 is set up for the controller and Gallery and has AMP enabled. Node 2 is a worker only node with the engine set to Original Only. Node 3 is a worker only node with its engine set to Both. In this scenario, running AMP workflows on Server is enabled and these workflows would only run on node 3. Original engine workflows would run on either node 2 or node 3. If node 3 is offline Original-engine workflows would still run on node 2, but AMP workflows would get stuck in the queue until node 3 came back online.

We recommend testing the AMP engine in a development environment before deploying it to production. Learn more about the AMP engine, including memory requirements, in the AMP Engine documentation.

Persistence

As the orchestrator of workflow executions and various other operations, the controller needs a location where it can maintain the available workflows, a queue of execution requests, and other information. Define where information critical to the functioning of the service is stored on the Persistence screen.

Screenshot of Controller Persistence screen which includes the following settings: Database Type, Data Folder, Advanced Database Connection, Database, and Persistence Options

Database Type

The controller maintains data in either SQLite or MongoDB databases. Server offers embedded SQLite or MongoDB options, as well as, a User-managed MongoDB option. If you are configuring the machine for a gallery, you must use MongoDB or User-managed Mongo DB.

  • SQLite: Creates an instance of the SQLite database. Recommended for lightweight and local deployments that use the scheduler.
  • MongoDB: Creates an instance of the MongoDB database. Recommended for heavier usage. 
  • User-managed MongoDB: Allows you to connect to your implementation of MongoDB.

If you switch between SQLite and MongoDB database types, scheduled jobs are not migrated. These jobs must be manually rescheduled.

We highly recommended that you have an automated backup system for your persistence database. For information on backing up MongoDB, see MongoDB Backups. To back up SQLite, you can zip or copy the persistence folder found in \ProgramData\Alteryx\Service\.

Data Folder

The Data Folder is the storage location for either the SQLite or embedded-MongoDB database files. If you select User-managed MongoDB, the Data Folder is disabled as it is configured in your MongoDB instance.

Advanced Database Connection

Select Advanced User-Managed Mongo DB if you require support for...

  • TLS/SSL
  • Replica Sets
  • Sharding
  • MongoDB Atlas

If you were using replica sets before the availability of the connection string option (2019.4 release or previous), you have to change to a connection string.

When you have selected this option, the Database section displays a MongoDB Connection field for you to specify your MongoDB connection string.

Screenshot of Advanced User-Managed MongoDB selected and the corresponding MongoDB Connection field that appears in the Database section

Connection String Tips and Examples

  • Supported connection string parameters are driver dependent. Parameters must be supported by all below listed supported drivers to be used in a connection string. Supported driver versions include...
    • c 1.15 (mongoc)
    • c++ 3.4.1 (mongocss)
    • c# 2.7.2 (mongoc#)
  • Special characters in usernames, passwords, or parameter values must be URL encoded.

Examples

  • On-premise, single-node example with SSL/TLS:

    mongodb://username:P%40ssw0rd@hostname.domain.tld:27017/AlteryxService?authSource=databasename&ssl=true

  • On-premise, replica set, example with SSL/TLS:

    mongodb://username:P%40ssw0rd@host01.domain.tld:27017,host02.domain.tld:27017,host03.domain.tld:27017/AlteryxService?authSource=databasename&replicaSet=rs0&ssl=true

  • Atlas example:

    mongodb+srv://username:P%40ssw0rd@host-0-1mngx.mongodb.net/AlteryxService?retryWrites=true&w=majority

See the MongoDB Connection String documentation for help formatting your connection string.

Database

If you selected User-managed MongoDB and you are not using the Advanced Database Connection, you will specify the Host location of the MongoDB instance, as well as, the Database Name in the Database section. If the MongoDB instance requires authentication, enter these in the Username and Admin Password fields. 

Screenshot of Database settings when User-managed MongoDB option is selected

For embedded MongoDB, the Host, Username, Admin Password, and Password fields are automatically populated. The Admin Password is for MongoDB Admins to set up backups and replica sets. The Password is used by all components to communicate with MongoDB. You can also use the Password for creating usage reports that connect to the database.

Screenshot of Database settings when MongoDB option is selected

Persistence Options

The controller maintains a queue of Alteryx jobs and caches uploaded files for use in executing those jobs. Workflow queues and results can quickly take up space if left unattended. You can flag various items and files for deletion after a specified number of days. These settings may help to reduce the amount of drive space used.

Mapping Configuration

On the Mapping Configuration screen, configure the machine to act as a Map Controller and define the thresholds for the tile and layer caching. Caching map tiles and the reference maps needed to render them increases performance. A larger cache size and increased time-to-live results in faster responses for previously requested tiles, but take up more memory and disk space. A smaller cache has the opposite effect.

  • Enable map tile controller: Select Enable map tile controller to allow the machine to serve map tiles rendered by workers. The Map Question and Map Input tools use these tiles for rendering maps.
    • Memory cache: This is the maximum number of map tiles stored in memory. 1,000 tiles require roughly 450 MB of memory. A higher memory cache results in more stored tiles to increase performance but requires more system resources.
    • Disk cache: This is the maximum amount of space allocated for caching map tile images on the hard drive. A higher disk cache results in greater consumption of drive space but may increase the performance of map tile requests.
    • Reference layer time to live: Map Questions and Map Input tools create reference layers and are driven by a .yxdb file. The controller can maintain a reference to this .yxdb file to help speed up rendering. This setting defines the amount of time to persist reference-layer information. Increasing this number may optimize the performance of frequently requested layers. Expired reference layers are regenerated the next time they are requested.

Remote Controller

If you have configured the machine to act as a worker, the Remote Controller screen is the only screen present under Controller. This is where you connect the machine to the controller machine. Enter the host location and the controller token to connect to the controller machine.

  • Host: Enter the host location of the controller machine.
  • Token: Enter the controller machine token. You can find the Controller Token in the System Settings of the controller machine on the Controller > General screen. See the General Configuration section in this article.

Select View or Hide to hide or display the controller token characters.
Screenshot of the Controller Remote screen which shows the Host and Token fields

What's Next?

Configure Worker.

Was This Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support.