Alteryx Server Admin cheat sheet

Alteryx Server runs on a multi-tier model: web tier (Controller/Gallery UI), engine tier (Worker nodes running AlteryxEngine), and persistence layer (MongoDB for metadata, a file store for workflow assets and outputs).

MongoDB stores users, subscriptions, schedules, workflow metadata, and results references; it does not store the workflow package itself.

The Controller node hosts the Gallery web application, the API, and the scheduler service that dispatches jobs to Workers.

A Worker node executes workflows; it must be able to reach the Controller and the MongoDB connection string to receive and report jobs.

The AlteryxService (Windows service) is the core server process; the Gallery is an ASP.NET web application served via IIS.

Persistence is split: MongoDB (metadata), a Server data/asset directory (workflow packages, outputs, temp files), and the runtime settings file (RuntimeSettings.xml).

Curated Collections and user permissions are metadata records in MongoDB, not filesystem ACLs.

A single-machine install colocates Controller, Worker, Gallery, and MongoDB; a distributed install separates these roles across hosts.

Install order for distributed deployments: MongoDB first, then Controller, then Workers, then configure the Gallery/Controller to point at MongoDB.

The Controller and Workers must run the same Alteryx version and the same set of installed tools/predictive macros; version mismatch breaks job execution.

RuntimeSettings.xml holds Controller/Worker role, MongoDB connection, and worker/queue settings; changes require an AlteryxService restart.

The Gallery settings (System Settings) control SMTP, authentication type, SSL, and worker assignment; these are stored in MongoDB, not just the local file.

Before upgrading, back up MongoDB and the Server data directory; upgrades migrate the MongoDB schema and are not trivially reversible.

Workers must be placed in maintenance mode or stopped during upgrade so they don't pick up jobs mid-migration.

SSL/TLS is configured at the IIS/Gallery level; the Controller-to-Worker and Controller-to-MongoDB channels should also be secured per deployment requirements.

The System Settings > Workers page shows worker registration status and lets admins assign workers to queues.

Authentication modes include built-in (Gallery-managed) accounts, Windows Integrated Authentication (NTLM/Kerberos), and SAML 2.0 single sign-on.

Authorization is role-based: Curator (admin) > Artisan > Viewer, plus custom roles; permissions are evaluated per-asset and per-collection.

The first user created during install becomes the initial Curator; additional Curators are granted via the Users admin page.

SAML configuration requires an Identity Provider (IdP) metadata/entity ID, assertion consumer URL, and attribute mappings for username/email.

API access uses API keys tied to a user; keys inherit that user's permissions and should be scoped/rotated.

Workflow run-as credentials (for data connections) are separate from the user's Gallery login; they determine what the engine can access at runtime.

Windows Authentication requires the Gallery to be configured for it in System Settings and IIS; switching auth modes affects existing session handling.

Least privilege: grant Viewer by default, Artisan for authors, Curator only to admins; restrict who can publish to shared districts/collections.

Schedules are stored in MongoDB and dispatched by the Controller's scheduler service to available Workers in the assigned queue.

A Worker picks up one job at a time per engine; concurrency is governed by the number of Workers/engines and queue assignment.

Schedule types include recurring (interval/cron-like), one-time, and triggered (e.g., on file arrival or via API).

Queue assignment determines which Workers can run a given schedule; a schedule with no eligible Worker stays pending.

The Scheduler admin page shows upcoming runs, run history, and lets Curators cancel or reschedule jobs.

Chained workflows execute sequentially; a failure in an upstream workflow can block downstream runs depending on configuration.

Worker health: a Worker that loses its Controller/MongoDB connection stops receiving jobs; check service status and connectivity.

Job results (outputs, logs) are written to the Server data directory and referenced by the run record in MongoDB.

Published workflows, apps, and macros are assets in the Gallery; each has an owner and an access list.

Districts are admin-defined groups (e.g., departments) used to scope who can see/publish content; users can belong to multiple districts.

Curated Collections are admin-curated groupings of assets shown to specified users/districts; membership is managed by Curators.

Asset permissions: owner, collaborators (can edit), and viewers (can run/view); permissions can be set per user or per district.

Subscription lets a user follow an asset to receive notifications on updates/runs; it does not grant run permission by itself.

Deleting an asset removes it from the Gallery but run history/metadata may persist; ownership transfer should precede offboarding a user.

Collections vs. Districts: Collections organize content for discovery; Districts govern publishing/visibility scope.

Sharing an app to a Collection exposes it to that Collection's audience without changing the asset's underlying district.

Key logs: AlteryxService log (Controller/Worker service), Gallery/IIS logs (web requests), and per-workflow engine logs (run results).

The Gallery Admin > Diagnostics/Logs area surfaces service logs; the Scheduler page shows run status and error messages.

MongoDB logs and connection health are primary indicators when the Gallery UI fails to load or jobs won't dispatch.

Common job failure causes: missing tool/macro on Worker, version mismatch, credential/permission errors, and data source connectivity.

A workflow that runs in Designer but fails on Server often depends on a local file path or a Designer-only connection not published to Server.

Worker not picking up jobs: check queue assignment, Worker registration in System Settings, and AlteryxService status.

Gallery 500/502 errors typically point to IIS, app pool, or MongoDB connectivity issues rather than workflow logic.

Run history retains status (Success/Error/Canceled) and links to engine logs for root-cause analysis.

Backup scope: MongoDB (metadata), the Server data/asset directory (workflows, outputs, temp), and RuntimeSettings.xml/config files.

Use mongodump/mongorestore (or a consistent snapshot) for MongoDB; copying live files without a consistent snapshot risks corruption.

Back up the Server data directory in coordination with MongoDB so metadata and assets stay consistent.

Recovery: restore MongoDB and the data directory to matching points in time, then restart AlteryxService and verify worker registration.

MongoDB replica sets provide HA for the metadata tier; a standalone mongod is a single point of failure.

Multiple Workers provide execution HA; the Controller and MongoDB are the critical single points unless made redundant.

Document and test restore procedures; an untested backup is not a verified recovery path.

Version upgrades should be preceded by a full backup; schema migrations complicate rollback.

Data connections are created by Curators in the Gallery and can be published/shared to users or districts; they hide credentials from workflow authors.

Connection types include database (ODBC/OleDB), file-based, and cloud connectors; credentials are stored encrypted in MongoDB.

Workflow credentials (run-as) determine the identity used at execution; they differ from the user's Gallery login.

Users need 'connect' permission on a data connection to use it in workflows; without it the workflow fails at runtime.

The AlteryxService account needs OS-level access to file shares and any local resources the workflow touches.

Connectivity troubleshooting: verify the Worker can resolve/reach the data source host and that drivers/ODBC DSNs are installed on every Worker.

Credentials stored on Server are encrypted with a key tied to the deployment; moving MongoDB without the matching key/config breaks decryption.

Test a connection from the Gallery/Worker context, not just from Designer, since service account and network path differ.

MongoDB = metadata (users, schedules, permissions); data directory = workflow packages and outputs.

Controller hosts Gallery, API, and scheduler; Workers run AlteryxEngine jobs.

AlteryxService is the core Windows service; Gallery is served via IIS.

Single-machine vs. distributed install separates Controller, Worker, and MongoDB roles.

RuntimeSettings.xml defines role and MongoDB connection; restart required after edits.

Curated Collections and permissions live in MongoDB, not filesystem ACLs.

Workers must reach Controller and MongoDB to receive/report jobs.

Engine tier executes workflows; web tier serves the UI/API.

Install order: MongoDB, Controller, Workers, then point Gallery at MongoDB.

Controller and Workers must match Alteryx version and installed tools/macros.

RuntimeSettings.xml holds role, MongoDB connection, worker/queue settings.

Gallery System Settings (SMTP, auth, SSL, workers) are stored in MongoDB.

Back up MongoDB and data directory before upgrading; migrations are not trivially reversible.

Stop/maintenance-mode Workers during upgrade to avoid mid-migration jobs.

SSL/TLS configured at IIS/Gallery level.

System Settings > Workers shows registration status and queue assignment.

Auth modes: built-in, Windows Integrated (NTLM/Kerberos), SAML 2.0 SSO.

Roles: Curator (admin) > Artisan > Viewer, plus custom roles; permissions per asset/collection.

First install user becomes initial Curator; add Curators via Users admin page.

SAML needs IdP metadata/entity ID, ACS URL, and username/email attribute mappings.

API keys inherit the owning user's permissions; scope and rotate them.

Run-as credentials (data connections) are separate from Gallery login identity.

Windows Auth requires Gallery + IIS configuration; switching modes affects sessions.

Least privilege: Viewer default, Artisan for authors, Curator for admins.

Schedules live in MongoDB; Controller scheduler dispatches to queue-eligible Workers.

One job per engine at a time; concurrency = Workers/engines in the queue.

Schedule types: recurring, one-time, triggered (file arrival/API).

No eligible Worker in queue = schedule stays pending.

Scheduler admin page shows upcoming runs, history, cancel/reschedule.

Chained workflows run sequentially; upstream failure can block downstream.

Worker losing Controller/MongoDB connection stops receiving jobs.

Job outputs/logs written to data directory, referenced by run record.

Published workflows/apps/macros are assets with owner + access list.

Districts are admin groups scoping publish/visibility; users can be in multiple.

Curated Collections are admin-curated asset groupings shown to users/districts.

Permissions: owner, collaborator (edit), viewer (run/view); per user or district.

Subscription follows an asset for notifications but does not grant run rights.

Transfer ownership before offboarding a user; deleting removes from Gallery.

Collections organize discovery; Districts govern publishing/visibility scope.

Sharing to a Collection exposes content without changing district scope.

Logs: AlteryxService log, Gallery/IIS logs, per-workflow engine logs.

Admin Diagnostics/Logs surfaces service logs; Scheduler shows run status/errors.

MongoDB health explains Gallery load failures and non-dispatching jobs.

Common failures: missing tool/macro, version mismatch, credentials, connectivity.

Runs-in-Designer-but-not-Server = local path or unpublished connection.

Worker idle: check queue assignment, registration, AlteryxService status.

Gallery 500/502 = IIS/app pool/MongoDB, not workflow logic.

Run history stores status and links to engine logs for root cause.

Backup scope: MongoDB, Server data directory, RuntimeSettings.xml/config.

Use mongodump/mongorestore or consistent snapshot; avoid copying live files.

Coordinate MongoDB and data-directory backups for consistency.

Restore matching points in time, restart AlteryxService, verify worker registration.

MongoDB replica set provides metadata-tier HA; standalone mongod is a SPOF.

Multiple Workers provide execution HA; Controller and MongoDB are critical.

Test restores; untested backup is not a verified recovery path.

Full backup before upgrades; schema migrations complicate rollback.

Data connections created by Curators, shared to users/districts, hide credentials.

Types: ODBC/OleDB database, file-based, cloud; credentials encrypted in MongoDB.

Run-as workflow credentials differ from the user's Gallery login.

Users need connect permission on a connection or the run fails.

AlteryxService account needs OS access to file shares and local resources.

Verify Worker can reach data source and has required drivers/DSNs installed.

Encryption key tied to deployment; moving MongoDB without it breaks decryption.

Test connections from Worker/service context, not just Designer.