Last modified: April 01, 2021

Configure the controller component on the Controller screens in System Settings. The controller is available for configuration if you configured the local machine to act as a controller.

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

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 Controller General Configuration screen which includes the following settings: Controller Token, Workspace, Logging, Scheduler, Insights

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


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.


The controller produces logs for event, 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.


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.


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


As the orchestrator of workflow executions and various other operations, the controller needs a location where it can maintain the workflows that are available, 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 Mongo DB: Allows you to connect to your own implementation of MongoDB.
  • For User-managed MongoDB, we only support MongoDB with SCRAM authentication. MongoDB with Kerberos authentication isn't supported.
  • 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\.
  • If you switch between SQLite and MongoDB database types, scheduled jobs aren't migrated. These jobs have to be manually rescheduled.

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...

  • 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 (mongocxx)
    • c# 2.7.2 (mongoc#)
  • Special characters in usernames, passwords, or parameter values must be URL encoded.


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


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


  • Atlas example:


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


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 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 takes 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 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 Page Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support. Can't submit this form? Email us.