Controller

Version:
2020.2
Last modified: September 08, 2020

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, Engine

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

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 e2 Engine to enable running workflows that use the Alteryx Multithreaded Processing (AMP) engine (also known as the e2 engine in Server) in this environment. During this preview release of AMP/e2 in Server, we recommend enabling the AMP engine for Desktop Automation and non-production testing environments only. The AMP engine is not yet recommended for production Server environments as it may cause performance and stability issues at scale. 

AMP/E2 Preview Release Best Practices

  • Limit your AMP/e2 workflows to run in non-production environments such as Desktop Automation.
  • Use a naming convention to differentiate AMP/e2 workflows and schedules from original engine workflows, such as “AMP-Quarterly Results Workflow” or “AMP-Scheduled Weekly ETL”.
  • Craft a single worker node to run AMP/e2 workflows and tag the worker with an AMP/e2-specific tag. Use best practices for the allocation of resources within that special worker node.
  • Tag any workflows that you’d like to run on AMP/e2 with the same AMP/e2-specific tag.

Persistence

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.

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