Alteryx Server Installation and Configuration Guide Configuration

Reference Guide
Alteryx Server Installation and
Configuration Guide
v 1.6,
1.6, May 2016
Contents
Alteryx Server Installation and Configuration Guide
Contents
Chapter 1 System Overview ........................................................................................................................................................ 5
Chapter 2 System Requirements .............................................................................................................................................. 6
Chapter 3 Installation ..................................................................................................................................................................... 7
Chapter 4 Licensing ......................................................................................................................................................................... 9
Chapter 5 Configuration ............................................................................................................................................................ 11
Configuring Alteryx Server Components on the Same Machine .................................................................... 11
System Settings Components............................................................................................................................................ 13
Environment ........................................................................................................................................................................... 13
Setup Type .......................................................................................................................................................................... 13
Workspace .......................................................................................................................................................................... 14
Controller ................................................................................................................................................................................. 14
General ................................................................................................................................................................................. 15
Persistence ......................................................................................................................................................................... 16
Mapping ............................................................................................................................................................................... 18
Worker........................................................................................................................................................................................ 19
General ................................................................................................................................................................................. 19
Run As .................................................................................................................................................................................... 20
Mapping ............................................................................................................................................................................... 20
Gallery ........................................................................................................................................................................................ 21
General ................................................................................................................................................................................. 21
SMTP ....................................................................................................................................................................................... 23
Persistence ......................................................................................................................................................................... 23
Engine......................................................................................................................................................................................... 24
General ................................................................................................................................................................................. 24
Proxy ...................................................................................................................................................................................... 25
Configuring a Worker Machine ......................................................................................................................................... 26
Chapter 6 Gallery Administration ......................................................................................................................................... 35
Logging in to the Gallery ...................................................................................................................................................... 35
Using Windows Authentication................................................................................................................................... 35
Using Built-In Authentication ....................................................................................................................................... 35
Administrative Functions..................................................................................................................................................... 36
System Settings .................................................................................................................................................................... 36
Subscription (Studio) Management........................................................................................................................... 37
Page 2
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Contents
Creating a New Subscription ................................................................................................................................... 37
Editing a Subscription.................................................................................................................................................. 38
Adding a User to a Studio ........................................................................................................................................... 39
User Management ............................................................................................................................................................... 40
Creating a New User...................................................................................................................................................... 40
Editing a User .................................................................................................................................................................... 41
Resetting a User’s Password .................................................................................................................................... 41
Disabling the Sign-Up Form ...................................................................................................................................... 42
Workflow Credentials Management ......................................................................................................................... 42
Creating New Workflow Credentials ................................................................................................................... 42
Sharing Workflow Credentials ................................................................................................................................ 43
Permissions Management .............................................................................................................................................. 43
Setting Default Permissions for New Users..................................................................................................... 43
Setting Permissions for Users and Groups....................................................................................................... 43
Workflow Management ................................................................................................................................................... 44
Adding a Workflow ........................................................................................................................................................ 44
Adding a Tag ...................................................................................................................................................................... 45
Editing a Workflow ........................................................................................................................................................ 46
Notification Management .............................................................................................................................................. 47
District Management......................................................................................................................................................... 48
Creating a District .......................................................................................................................................................... 48
Media Management ........................................................................................................................................................... 48
Theme Management .......................................................................................................................................................... 49
Page Management .............................................................................................................................................................. 49
Link Management ................................................................................................................................................................ 50
Chapter 7 Troubleshooting....................................................................................................................................................... 51
My workflows are always in a “Queued” state when scheduled or during validation................. 51
Maps in the Map Input, Report Map, and Map Question tools don’t show up. ................................. 51
I have configured Alteryx Server to run workflows as a specified user, but they are failing.... 52
I need to temporarily shut down Alteryx Server. ............................................................................................... 52
Chapter 8 MongoDB Backup and Restore ........................................................................................................................ 53
Creating a Backup................................................................................................................................................................ 53
Restoring from a Backup ................................................................................................................................................. 53
Using a Backup ...................................................................................................................................................................... 53
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 3
Contents
Alteryx Server Installation and Configuration Guide
Appendix ............................................................................................................................................................................................. 54
Enabling SSL for Alteryx Server ......................................................................................................................................... 54
Obtaining an SSL Certificate’s Thumbprint........................................................................................................... 54
Configuring a Port to Use an SSL Certificate ........................................................................................................ 55
Configuring the Alteryx Server Gallery URL .......................................................................................................... 56
Installing Alteryx Custom Tool Packages .................................................................................................................... 57
Glossary ............................................................................................................................................................................................... 58
Document History ......................................................................................................................................................................... 60
Page 4
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 1 System Overview
Chapter 1 System Overview
The Alteryx platform comprises four primary components:
The Alteryx Designer is a Windows software application that provides an intuitive drag-anddrop user interface for users to create repeatable workflow processes. Users can use these
workflows to blend and enrich data from a range of sources, perform advanced analytics, and
quickly produce results that can be easily shared with others. The Designer executes the
workflows through a local instance of the Alteryx Engine. Alternatively, in an Alteryx Server
deployment, the Scheduler interface component within Alteryx Designer allows users to
schedule workflows to be executed at predetermined times or specific recurring intervals.
Additionally, users may use Alteryx Designer to publish their workflows to the Alteryx Gallery
where others can have access to running them.
The Alteryx Engine executes the workflows that are built in the Alteryx Designer, provides
high-speed data processing and analytics functionality, and produces the output. The Engine
supports direct connections to various data sources for accessing the data and then
processes it in-memory during the execution of the workflow. The Engine can be entirely selfcontained in an Alteryx Designer deployment, scaled across an organization via an Alteryx
Server deployment, or deployed in the cloud via the Alteryx Analytics Gallery.
The Alteryx Service allows the Alteryx Engine to be deployed across multiple servers,
providing a highly scalable architecture for the scheduling, management, and execution of
analytic workflows. The Alteryx Service uses a Controller-Worker architecture where one
server acts as the Controller and manages the job queue and the others act as Workers and
perform the work. The Service relies upon the Service Persistence tier to store information
critical to the functioning of the Service and also serves content and information to the
Gallery when it requests it.
The Alteryx Gallery is a cloud- or self-hosted application for publishing, sharing, and
executing workflows. Alteryx offers the Alteryx Analytics Gallery where users can sign up and
share workflows, apps, and macros publicly or with selected users. Additionally, an Alteryx
Server deployment allows companies the ability to offer a private Gallery to their internal
users hosted on their own server infrastructure.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 5
Chapter 2 System Requirements
Alteryx Server Installation and Configuration Guide
Chapter 2 System Requirements
Recommended
High Performance
Performan ce
64-bit
Quad Core Intel Xeon (single chip)
2.5GHz
64-bit
Quad Core Intel Xeon (single chip)
2.5GHz
Memory
16GB
32GB
Disk size
1TB
1TB
Windows Server 2008 R2 or later
Windows Server 2008 R2 or later
CPU
Operating System
*Alteryx is supported on desktop machines, stand-alone servers, and virtual machine environments.
Administrator
privileges:
Predictive Tools
Install:
Install :
Base Address:
Address:
•
Administrator rights are required to install Alteryx Server.
•
SMTP Server:
•
Default Gallery
Administrator:
•
Database Type:
•
The server must be installed with the Predictive Tools in order
for workflows that use Predictive Tools to be able to run.
This is the URL that users will use when they go to the Gallery.
The field defaults to http://localhost/gallery/ which can be used
to run the Gallery locally on the machine.
Notifications and account validations are managed via email.
SMTP host information is required for Gallery email notifications.
This depends on the type of authentication selected when the
server settings were configured. The Administrator is given
permission to access the Gallery and manage users and workflows.
• If using Windows Authentication provide the user name
of a domain user.
• If using Built-in Authentication provide the email
address and password of the site administrator during
configuration and then provide the first name and last
name during login to complete the Gallery Admin
account registration.
If you are configuring the machine to run a Gallery instance you
must use MongoDB.
• For embedded MongoDB the host, user name, and
password automatically generated will be available for
you to use.
• For “User-managed MongoDB” you will need to specify
this information based on the configuration of your
MongoDB instance(s).
• Important: If you were previously using SQLite for
Alteryx Scheduler, jobs must be manually re-scheduled
when switching to MongoDB.
Page 6
•
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 3 Installation
Chapter 3 Installation
1. Download the Alteryx Server installation package.
2. Run the Alteryx Server Installer.
3. Confirm the destination folder and click Next.
Next
4. Select the I accept the license agreement checkbox and click Next.
Next
5. Select one of the following options and click Finish.
Finish
• Configure Server now – Opens the System Settings window so you can
configure the server.
• Close and run Alteryx Designer later – Closes the installation window and
does not open the System Settings window for configuring the server system
settings. The System Settings window can be accessed at any time via the
System Settings icon on your desktop.
• Install Predictive Tools – Installs the Predictive Tools as part of the Designer.
The Predictive Tools are a set of tools that use R, an open-source code base
used for statistical and predictive analysis. Selecting this option during the
server installation will launch the Alteryx R installer and install the R program
and the Predictive tools that use R. The Predictive Tools must be installed in
order to use the Predictive Macros in Alteryx. To install the tools at a later time,
go to Options > Download Predictive Tools in the Alteryx Designer.
• Migrate Mongo Database – Initiates the data migration process to back up
an existing MongoDB database and create a new one. This option should
selected in addition to any of the other three options.
When updating from Alteryx 9.5 or earlier, Alteryx Server deployments using
the default embedded MongoDB will be prompted to run a migration utility to
perform the Mongo 3.0 upgrade. Alteryx Server will not function until this
migration has been completed.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 7
Chapter 3 Installation
Alteryx Server Installation and Configuration Guide
Deployments of Alteryx Server utilizing a user-managed mongo instance must
upgrade their MongoDB deployment to 3.0 as well.
6. Click Begin Backup and Migration.
Migration
• Backup Folder: Browse to the location where the database backup should be
created. This is where a complete copy of the original database will be saved.
• New Data Folder: Browse to the location where the new database should be
created. This is where the newly migrated data will be saved.
7. When the migration is complete, click OK.
OK A MongoDB_PreAlteryx10 folder and a
Mongo_Alteryx10 folder is created.
Page 8
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 4 Licensing
Chapter 4 Licensing
If Alteryx Server has not yet been licensed, you will be prompted to license it. Follow the
steps on the license activation screens to install your license.
1. The Install License dialog box opens. Click OK to install a license.
2. Enter the License Key and your Email Address and click Next.
Next
3. Enter the appropriate information in the fields and click Submit.
Submit
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 9
Chapter 4 Licensing
Alteryx Server Installation and Configuration Guide
4. Once the license has been activated the expiration date displays. Click Get
Started to begin using Alteryx Server. The System Settings window should
automatically open so you can configure the server.
Page 10
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
Chapter 5 Configuration
Once the Alteryx Server components have been installed and the product is licensed, the
System Settings window opens so you can configure the server settings. If the window
does not automatically open you can access it via the System Settings icon on your
desktop.
The Alteryx Server can be configured in a basic setup, with all components running on the
same machine, or it can be configured as a multi-node instance involving multiple
machines. The following steps will help you configure Alteryx Server with all components
enabled on the same machine.
Configuring Alteryx Server Components on the Same Machine
1. Double-click the System Settings icon on your desktop.
The System Settings window opens. The Status screen displays the components
of the system that have been enabled by default.
2. Click Next on each screen of System Settings to navigate through the settings for
the Environment,
Environment Controller,
Controller Worker,
Worker Gallery,
Gallery and Engine components. Many of
them have default values defined but you may need to enter or modify
information depending on how you want to configure your machine.
*Each component is explained in the System Settings Components section of
this guide.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 11
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
3. Once all components have been configured the Finalize Your Configuration
screen displays. Click Finish to complete the configuration process and save
changes to the components.
4. The Status screen displays the components of the system that have been enabled
on the machine. Click Done to close the System Settings window.
*Refer to the System Settings Components section of this guide for guidance on
configuring each component.
Page 12
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
System Settings Components
Environment
The Environment component of System Settings includes the settings for identifying the
type of configuration for the machine, as well as a global workspace for other
components to use as a root location for file storage.
Setup Type
The Environment > Setup Type screen allows the user to define the components of the
Alteryx Server architecture to enable on the local machine. The complete Alteryx Server
can be enabled on a single machine, selected components can be enabled on the
machine, or certain components can be enabled or disabled to accommodate for a multimachine, scaled Alteryx Server deployment. The options available are:
•
•
•
•
Designer Only:
Only: Enables only the Alteryx Designer component on the local
machine. Scheduler and Gallery functionality will not be enabled or configurable.
Use this option when you are installing on one machine and multiple people are
sharing that machine to build and run workflows.
Designer and Scheduler Only:
Only: Enables the Alteryx Designer and the Scheduler
component. Gallery functionality will not be enabled or configurable. Use this
option when you want users on the machine to build and run workflows, as well
as schedule workflows to be run in the future.
Complete Alteryx Server:
Server: Enables the entire Alteryx Server architecture to run on
the local machine. This includes the Alteryx Designer, Scheduler, and Gallery. Use
this option if you are running in a single machine environment and want the
entire Alteryx Server functionality.
Custom:
Custom: Allows you to enable or disable specific components for the local
machine. Use this option for multi-machine deployments of Alteryx Server when
you want different components enabled on different machines.
o Enable Controller:
Controller: Enables the Controller component on the local
machine, allowing it to orchestrate workflow job executions to Workers.
o Enable Worker:
Worker: Enables the Worker component on the local machine,
allowing it to execute workflow job requests from a Controller.
o Enable Gallery:
Gallery: Enables the Gallery component on the local machine. If
this option is enabled, the Default Gallery Administrator must be
specified on the Gallery > General screen and the SMTP Server
information must be specified on the Gallery > SMTP screen for email
notifications.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 13
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
Workspace
The Environment > Workspace screen allows the user to define a root location to act as
the global workspace. This path will be used as the base for other configuration options
that determine where temporary files, log files, and database files can be stored. Subfolders for the specific items can be created to use this global workspace, or can be
customized later in the configuration to write to a different location. This path should
point to a location that is safe to store large amounts of files.
Controller
The Alteryx Service Controller is responsible for the management of the service settings
and the delegation of work to the Alteryx Service Workers. If the local machine is
configured to act as a Controller, the Controller component is available for configuration.
Only one machine may be enabled as a Controller in a deployment.
Page 14
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
General
The Controller > General screen includes configuration options such as where temporary
files and log files should be stored and what information should be logged.
•
Controller Token:
Token: A secret key that is used to establish communications between
the Controller machine and the machine using Designer as well as between the
Controller machine and the Worker machine.
If the machine using Designer is separate from the Controller machine and you
want to schedule a workflow to run in the future, you must add the Controller
token in the Schedule Workflow screen in Designer in order to connect to the
Controller and have the job run from there.
You will also need the Controller Token if you want to have one machine act as a
Controller and another machine act as Workers. Set the first machine up as a
“Remote Controller”, copy the Controller Token and add it when configuring the
Worker machine so that the machines can communicate with each other.
The Controller token is auto-generated for you. If you want to change your token,
click Regenerate
Regenerate.
erate You will get the following message stating the service will be
stopped:
Token regeneration should only be done if absolutely necessary, such as the token
becoming compromised. Regenerating the token will require updating any Gallery
or Worker nodes in the deployment.
•
•
Workspace:
Workspace: The Controller Workspace is the location where the Controller will
store temporary or cache files. By default it will be a folder within the global
workspace folder. This path should point to a location that is safe to store large
amounts of files.
Logging:
Logging: The Controller component contains functionality to produce logs of
events such as services being started, shut downs, execution requests, etc. which
can be helpful for troubleshooting issues. This information is stored in files on the
file system.
• Level: Allows you to choose the types of messages that should be
captured. (None = No logging; Low = Log only Emergency, Alert, Critical, and
Error type messages; Normal= Log everything in Low, plus Warnings and
Notices; High = Log all message types.) A level of “None” or “Low” may be
sufficient for production environments where little logging is needed
while a level of “High” will log more messages to help with troubleshooting.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 15
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
File size:
size: Allows you to specify the maximum size of a log file.
Enable log
lo g file rotation:
rotation: Log files can become quite large depending on
how the system is running and the level of the logging. Enabling log file
rotation ensures that when the current log file reaches its maximum size it
will be placed in an archive file and logs will get written to a new file. This
will help to prevent creating large log files that are difficult to consume in
standard log readers.
Enable Scheduler autoauto -connect: Allows users on this machine to auto-connect to
the Scheduler. Enable this if you have difficulties connecting to the Scheduler.
•
•
•
Persistence
The Alteryx Service includes a persistence layer that it uses to store information critical to
the functioning of the service, such as Alteryx application files, the job queue, and result
data. The Service supports two different mechanisms for persistence: SQLite and
MongoDB. For lightweight and local deployments SQLite is adequate for most scheduling
needs. For heavier usage, or if the Alteryx Gallery is deployed, MongoDB must be used.
Since the Controller acts as an orchestrator of workflow executions and various other
operations it needs a location where it can maintain the workflows that are available, a
queue of execution requests, and other information. These settings can be defined in the
Controller > Persistence screen.
When switching between SQLite and MongoDB database types, previously scheduled
jobs will not be automatically migrated. These jobs will need to be manually re-scheduled.
•
Database Type:
Type: The Controller maintains data in either SQLite or MongoDB
databases. Alteryx 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.
It is highly recommended that you provide an automated backup system for
whatever persistence mechanism you choose.
Page 16
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
SQLite:
SQLite: Creates an instance of the SQLite database for you to use. For
lightweight and local deployments that use the Scheduler, SQLite is
sufficient.
• MongoDB:
MongoDB : Creates an instance of the MongoDB database for you to use.
For heavier usage, or if the Alteryx Gallery is deployed, MongoDB must be
used.
• UserUser-managed Mongo DB:
DB : Allows you to connect the Service to your own
implementation of MongoDB.
Data Folder:
Folder: This is the location where either the SQLite or embedded MongoDB
database files should be stored. If you select UserUser-managed MongoDB this
option will be disabled as it will be configured directly in your own MongoDB
instance.
Database:
Database: For embedded MongoDB the host, username, and password
automatically generated will be available for you to use if you would like to access
and interrogate the data. The Admin Password is for MongoDB Admins to setup
backups and replica sets. The user Password is the one all of the components use
to communicate with MongoDB and can be used for creating usage reports that
connect to the database.
For UserUser-managed MongoDB you will need to specify this information based on
the configuration of your MongoDB instance.
Persistence Options:
Options: The Controller maintains a queue of Alteryx jobs, as well as
caches uploaded files for use in executing those jobs. Workflow queues and
results can quickly take up space if left unattended. You can specify whether or
not job results and files should be deleted and, if so, how many days they should
remain. These settings may help to reduce the amount of drive space necessary as
the system is used.
•
•
•
•
•
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 17
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
Mapping
The Controller can be enabled to also handle requests for mapping operations, such as
orchestrating requests for map tile generation and caching. The Controller > Mapping
screen allows you to configure whether or not the machine should act as a Map
Controller, as well as the thresholds for the tile and layer caching. The map tiles and the
reference maps needed to render them can be cached to increase performance. A larger
cache size, and increased time to live, will result in faster responses for tiles that have
been requested before, but will take up more memory and disk space; a smaller cache has
the opposite effect.
•
•
•
•
Page 18
Enable map tile controller:
controller: Configuring the machine to enable a map tile
Controller allows it to serve up map tiles that are rendered by Workers. These tiles
are used for rendering maps in the Map Question and Map Input tools.
Memory
Memory cache: This is the maximum number of map tiles that will be stored in
memory. 1,000 tiles will require roughly 450 MB of memory. A higher memory
cache will result in more tiles being stored to increase performance, but will
require more system resources.
Disk cache:
cache: This is the maximum amount of space to allocate for caching map tile
images on the hard drive. A higher disk cache will result in greater consumption of
drive space but may increase performance of map tile requests.
Reference layer time to live:
live: Reference layers are created by Map Questions and
Map Input Tools and are driven by a YXDB file. The Controller can maintain a
reference to this YXDB to help speed up rendering. This setting allows you to
define the amount of time to persist reference layer information. Increasing this
number may help optimize performance of frequently requested layers. If a
reference layer expires, it will be generated again the next time it is requested.
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
Worker
The Alteryx Service Worker is responsible for executing analytic workflows. There must
be at least one machine enabled as a Worker in order to execute workflows through the
Service. You may configure the same machine to be both the Controller and a Worker. The
actual number of Workers needed will depend upon the required performance for the
system. If the local machine is configured to act as a Worker, the Worker component will
be available for configuration.
General
The Worker > General screen includes configuration options such as where temporary
files should be stored and whether the machine can run scheduled workflows.
•
•
•
•
•
•
Workspace: The Workspace is the location where the Worker will store temporary
or cache files, as well as unpackaged workflows for use when executing
workflows. By default it will be the same as the Controller folder. This path should
point to a location that is safe to store large amounts of files.
Allow machine to run scheduled Alteryx workflows:
workflows: Enabling this machine to
run scheduled Alteryx workflows will allow it to take requests to run workflows
from the Scheduler or from the Gallery. In multi-node deployments, you may want
to uncheck this option if you have another machine that will be running
workflows, and want this machine to process map requests only.
Workflows
Workflows allowed to run simultaneously:
simultaneously: This is the maximum number of
scheduled workflows that are allowed to run simultaneously on this machine. You
may want to increase this number to improve the responsiveness of scheduled
jobs, but the overall processing time may be increased.
Maximum sort/join
sort /join memory usage (MB):
(MB): This will restrict the amount of memory
Alteryx will use when encountering Sort or Join tools in a workflow. A general rule
for an appropriate setting is to be ½ the amount of system memory available,
divided by the number of simultaneous workflows allowed to run.
Cancel jobs running longer than (seconds):
(seconds): If you do not want jobs to run for an
extended period of time, you can use this setting to force jobs to cancel after a
certain amount of time has passed. This will help to free up system resources that
might otherwise be taken up by unintentionally long running jobs.
Quality of Service:
Service: Quality of Service (QoS) is used to manage resource allocation
in an environment where multiple workers are deployed by restricting which jobs
will be run by each Worker. For normal operation with one machine configured as
a worker, set this value to 0.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 19
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
Run As
If a Worker machine needs to run workflows that access files or data from a location that
requires specific credentials to access it, the machine can be configured to run the
workflows as a specified user or account. To have the machine run as a different user,
enter the Domain, Username, and Password.
Mapping
The machine can be enabled to act as a Map Worker, which will allow it to render map
tiles for Map Questions and the Map Input Tool. You can specify the number of processes
to be used for tile rendering. The more processes allowed, the more simultaneous tiles
can be rendered, but it will take up more system resources.
Page 20
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
Gallery
The Alteryx Gallery is a cloud-based application for publishing, sharing, and executing
workflows. It communicates directly with the Alteryx Service for the management and
execution of the workflows and utilizes a MongoDB persistence layer for all state
maintenance. This allows the Gallery to be deployed across multiple servers behind a
load balancer (not provided as part of the architecture) in order to support horizontal
scalability.
Alteryx offers a public Gallery (https://gallery.alteryx.com/), where users can sign up and
share workflows, apps, and macros, and a private Gallery, which allows companies to
offer the Gallery to internal users hosted on their own server infrastructure.
General
The Gallery > General screen includes configuration options such as where temporary
files and log files should be stored and what type of authentication you want to use to
access it.
•
•
•
•
Gallery Workspace:
Workspace: The workspace is the location where the Gallery will store
temporary files. By default it will be a folder within the global workspace folder.
This path should point to a location that is safe to store large amounts of files.
Logging Directory:
Directory: This is the location where log messages specific to the Gallery
services will be stored.
Base Address: This is the URL that users will use to go to the Gallery. Although the
domain configuration must be done elsewhere, this URL is used in areas such as
email content when links to workflows are made available.
Enable SSL: Enabling this changes the URL in the Base Address field to https. If
you enable SSL and your certificate is set to a port other than the default 443,
specify the port in the URL as well (e.g., https://localhost:445/gallery/). For
information on how to install an SSL certificate on the machine, see the Appendix.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 21
Chapter 5 Configuration
•
Alteryx Server Installation and Configuration Guide
Authentication Type:
Type: Alteryx Server supports built-in authentication as well as
integrated Windows Authentication.
• Built-in Authentication: Allows users to access the Gallery using an email
address and password.
• Windows Authentication: Allows users to access the Gallery with internal
network credentials.
• Windows Authentication with Kerberos: Allows users to access the Gallery
with internal network credentials using Kerberos authentication protocols.
Once an authentication type has been selected it should not be changed or Gallery
functionality may be compromised.
•
•
Default Gallery Administrator:
Administrator: A Gallery Administrator account must be created
in order to manage users, workflows, etc. If using Built-in authentication, enter the
email address of the administrator (ex. [email protected]). If using Integrated
Windows Authentication, specify the user account (ex. Domain\Username). If the
Gallery is enabled on the Environment > Setup screen, the Default Gallery
Administrator is a required field.
Default Run Mode:
Mode: Determines the level that workflows are permitted to run in
the Gallery. Workflows that contain certain tools or access may need to be
blocked. If a user has a workflow that uses one of the prohibited tools in a safe
manner, they may request an exemption from the Gallery Admin. Exemptions are
managed in the Admin > Workflows page in the Gallery.
• Unrestricted: Any workflow can be run.
• SemiSemi -safe: Workflows accessing or storing data on non-local drives will be
blocked from running.
• Safe: Workflows accessing or storing data on non-local drives, or using
certain tools and events, will be blocked from running. The tools and
events include: Run Command tool, Download tool, Email tool, R tool, Run
Command event, and Send Email event.
Safe and Semi-safe options can only be used if the Worker > Run As setting has been enabled.
Page 22
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
SMTP
The Gallery > SMTP screen includes configuration options for enabling SMTP. If the
Gallery is enabled on the Environment > Setup screen, the information on the SMTP page
is required so that the server can send email notifications for various events such as
registering your Gallery account, changing your password, or sharing a workflow.
Enter the From Email
Email,
mail Host,
ost Port,
Port Username,
sername and Password information for your SMTP
server. (The From Email, Host, and Port are required, while Username and Password are
only required if the SMTP server configuration requires it.) Click the Test button to make
sure it is set up correctly. If the settings are valid, a test email will be sent to the
designated email address.
Uncheck the Enable SMTP option to complete the Server setup without enabling SMTP.
Email notifications from the Gallery will be disabled until SMTP settings are configured.
If the SMTP server has been setup to use SSL, select the Use SSL checkbox.
Persistence
•
•
Use Controller Persistence Settings:
Settings: The Gallery stores information for users,
collections, etc. in MongoDB. Select this option (which is on by default) for the
Gallery to use the same persistence options as the Controller > Persistence
settings. If you would like the Gallery to use a different MongoDB connection than
the Controller, specify the host, user name, and password information.
Same settings as Web Persistence:
Persistence: Indices for search functionality within the
Gallery are also stored on Mongo. Select this option (which is on by default) for
the Search indices to be persisted using the same options as the Web Persistence.
If you would like the search indices to use a different MongoDB connection than
the Web Persistence, specify the host, user name, and password information.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 23
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
Engine
The Alteryx Engine consumes Alteryx workflows and provides high-speed data processing
and analytics functionality. This process can be entirely self-contained in the Alteryx
Designer, scaled across an organization via the Alteryx Service, or deployed in the Cloud
via the Alteryx Gallery.
General
The Engine > General screen includes configuration options such as where temporary
files and log files should be stored and options for specifying system resource usage to
optimize performance.
•
•
•
•
•
•
Page 24
Temporary Directory:
Directory: The Engine Temporary Directory is the location where
temporary files used in processed workflows will be stored. This path should point
to a location that is safe to store large amounts of files.
Logging Directory:
Directory: Each time a workflow is run, output logs are produced. These
logs will be written to the directory specified in this field. A blank logging
directory will disable logging.
Package Staging Directory: When editing workflows stored in a Gallery, the
Package Staging Directory will be used to temporarily house files associated with
the workflow. By default, these files will be written inside of the Engine
Temporary Directory.
Memory Limit per Anchor: The maximum amount of memory that is used to
consume data for each output anchor for tools in a workflow. The default is 1024
KB (1 MB). This setting is typically not changed.
Default Sort/Join Memory Usage:
Usage: This is the minimum amount of memory that
the Engine will consume while performing operations such as Sorts and Joins
within a workflow. Generally this value should not change.
Default Number of Processing
Processing Threads:
Threads: Some tools and operations can take
advantage of multiple processing threads. Generally this value should not be
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
•
•
•
Chapter 5 Configuration
changed, and the default value is the number of available processor cores plus
one.
Allow Users to Override These Settings:
Settings: This option will either allow or prevent
users from overriding the above settings. If checked, users can specify their own
memory usage, processing threads, etc. If not checked, the users will assume the
settings provided.
Run Engine at a Lower Priority:
Priority: This option should be checked if you are running
other memory intensive applications simultaneously. It is also recommended that
this setting be checked for a machine configured to run the Gallery.
Allow User Alias to Override the System Alias:
Alias: With this option checked, any user
alias that is specified in the Alias Repository can take priority over a system alias.
Proxy
Alteryx will use a proxy, if one is set up, to access the internet, rather than directly
connecting to an internet host. These proxy credentials will be used by the Engine when
running workflows in the Gallery or as a scheduled job.
If a proxy server has been set up, and a username and password is required, then they can
be entered on the Engine > Proxy screen. If a proxy server has not been set up, this screen
will not display.
•
Proxy requires password:
password: Select this option to enter the Username and Password
that will be sent to the proxy for authentication.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 25
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
Configuring a Worker Machine
Once the Alteryx Server has been installed it is scalable to accommodate for higher levels
of usage by enabling certain components on additional machines. Engine processing
capabilities can be increased by configuring an additional machine to act as a Worker.
Each additional Worker machine must be configured with the unique security token of
the Controller to be able to communicate with it. The security token is available as part of
the System Settings for the machine configured as the Controller.
1. To locate the Controller security token, double-click the System Settings icon on
the machine configured as the Controller.
The System Settings window opens. The Status screen displays the components
of the system that have been enabled.
Page 26
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
2. Click Next on each screen of System Settings to navigate through the settings for
the Environment until you reach the Controller > General screen.
3. Click the View button to display the Controller token. Copy the token and save it
to use later.
4. Locate and copy the Computer Name for the machine configured as the
Controller. Copy the name and save it to use later.
5. Install the Server on the machine to be configured as the Worker.
6. Double-click the System Settings icon to open the System Settings window.
7. Click Next to go to the Environment > Setup Type screen.
8. To enable only the Worker component on the machine select the Custom option,
and then the Enable Worker option, and click Next.
Next
The Alteryx Designer is automatically enabled by default any time the Custom
option is selected.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 27
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
9. On the Environment > Workspace screen define a root location to act as the
global workspace and click Next.
Next This path will determine where temporary files,
log files, and database files can be stored.
10. On the Controller
Control ler > Remote screen paste the Computer Name in the Host field
and the Controller token in the Token field so that the Controller machine and the
Worker machine can communicate with each other.
Page 28
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
11. Click the Test button to verify the connection to the Controller machine. If the
token is authenticated, a Success message displays. Click Next to go to the next
screen.
If an Error message displays, verify the Computer Name and Token of the
Controller machine and ensure the Alteryx Service for the Controller is running.
12. On the Worker > General screen, configure the options as needed and click Next
to continue.
• Workspace: The Workspace is the location where the Worker will store
temporary or cache files, as well as unpackaged workflows for use when
executing workflows. This path should point to a location that is safe to store
large amounts of files.
• Allow machine to run scheduled Alteryx workflows:
workflows: Enabling this machine
to run scheduled Alteryx workflows will allow it to take requests to run
workflows from the Scheduler or from the Gallery. In multi-node deployments,
you may want to uncheck this option if you have another machine that will be
running workflows, and want this machine to process map requests only.
• Workflows
Workflo ws allowed to run simultaneously: This is the maximum number of
scheduled workflows that are allowed to run simultaneously on this machine.
You may want to increase this number to improve the responsiveness of
scheduled jobs, but the overall processing time may be increased.
• Maximum sort/join memory usage:
usage: This will restrict the amount of memory
Alteryx will use when encountering Sort or Join tools in a workflow. A general
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 29
Chapter 5 Configuration
•
•
Alteryx Server Installation and Configuration Guide
rule for an appropriate setting is to be ½ the amount of system memory
available, divided by the number of simultaneous workflows allowed to run.
Cancel jobs after timeout:
timeout : If you do not want jobs to run for an extended
period of time, you can use this setting to force jobs to cancel after a certain
amount of time has passed. This will help to free up system resources that
might otherwise be taken up by unintentionally long running jobs.
Quality of Service:
Service: Quality of Service (QoS) is used to manage resource
allocation in an environment where multiple workers are deployed by
restricting which jobs will be run by each Worker. For normal operation with
one machine configured as a worker, set this value to 0.
13. On the Worker > Run As screen, configure the options as needed and click Next to
continue.
If a Worker machine needs to run workflows that access files or data from a
location that requires specific credentials to access it, select the Run as a
different user option. To have the machine run as a specified user or account,
enter the Domain,
Domain Username,
Username and Password.
Password
Page 30
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 5 Configuration
14. On the Worker > Mapping
Mapping screen, configure the options as needed and click Next
to continue.
The machine can be enabled to act as a Map Worker, which will allow it to render
map tiles for Map Questions and the Map Input Tool. You can specify the number
of processes to be used for tile rendering. The more processes allowed, the more
simultaneous tiles can be rendered, but it will take up more system resources.
15. Since the Gallery component was not selected in the Setup Type screen, there are
no settings to be completed. Click Next to continue.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 31
Chapter 5 Configuration
Alteryx Server Installation and Configuration Guide
16. On the Engine > General screen, configure the options as needed and click Next
to continue.
• Temporary Directory: The Engine Temporary Directory is the location where
temporary files used in processed workflows will be stored. This path should
point to a location that is safe to store large amounts of files.
• Logging Directory. Each time a workflow is run, output logs are produced.
These logs will be written to the directory specified in this field. A blank
logging directory will disable logging.
• Package Staging Directory: When editing workflows stored in a Gallery, the
Package Staging Directory will be used to temporarily house files associated
with the workflow. By default, these files will be written inside of the Engine
Temporary Directory.
• Memory Limit per Anchor: The maximum amount of memory that is used to
consume data for each output anchor for tools in a workflow. The default is
1024 KB (1 MB). This setting is typically not changed.
• Default Sort/Join Memory Usage: This is the minimum amount of memory
that the Engine will consume while performing operations such as Sorts and
Joins within a workflow. Generally this value should not change.
• Default Number of Processing Threads: Some tools and operations can take
advantage of multiple processing threads. Generally this value should not be
changed, and the default value is the number of available processor cores plus
one.
• Allow Users to Override: This option will either allow or prevent users from
overriding the above settings. If checked, users can specify their own memory
usage, processing threads, etc. If not checked, the users will assume the
settings provided.
• Run Engine at a Lower Priority: This option should be checked if you are
running other memory intensive applications simultaneously. It is also
Page 32
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
•
Chapter 5 Configuration
recommended that this setting be checked for a machine configured to run
the Gallery.
Allow User Alias to Override: With this option checked, any user alias that is
specified in the Alias Repository can take priority over a system alias.
17. Once all components have been configured the Finalize Your Configuration
screen displays. Click Finish to complete the configuration process and save
changes to the components.
18. The Status screen displays the components of the system that have been enabled
on the machine. Click Done to close the System Settings window. The Worker
machine is now configured to execute workflow job requests from the Controller
machine.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 33
Chapter 5 Configuration
Page 34
Alteryx Server Installation and Configuration Guide
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
Chapter 6 Gallery Administration
Once Alteryx Server has been installed and configured, if the Gallery has been enabled,
you can open a browser and go to the Gallery URL you specified in the Gallery > General >
Base Address field. The steps for logging in to the Gallery are dependent upon the type of
authentication selected when the server settings were configured.
Logging in to the Gallery
Using Windows Authentication
If you have configured the site to use Windows authentication on the Gallery > General
page, when you go to the Gallery URL you may be prompted to enter your domain
credentials in order to log in.
1. Go to the URL specified in the Gallery > General > Base Address field during
configuration.
2. Enter your User Name and Password.
Password
3. Click OK to log in to your Gallery account.
Using Built-In Authentication
If you have configured the site to use Built-in authentication on the Gallery > General
page, you must take additional steps when you log in the first time to create your Gallery
Admin account.
1. Go to the URL specified in the Gallery > General > Base Address field during
configuration.
2. Click Sign In.
In
3. Fill out the Sign Up form using the email address and password entered for the
Default Gallery Administrator.
Administrator
4. Click Sign Up.
Up
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 35
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
Administrative Functions
Once you have logged in to the Gallery you can access the Admin page by hovering over
the Settings icon and clicking the Admin option.
The Admin page opens and the following functions display in the left menu.
•
•
•
•
•
•
•
•
•
•
•
•
System
Subscriptions (also known as Studios)
Users
Workflow Credentials
Permissions (when using Windows Authentication only)
Workflows
Notifications
Districts
Media
Theme
Pages
Links
System Settings
Several options can be enabled via the System Settings page.
• Disable user registration:
registration: When checked, disables the Sign Up area on the
Gallery so that new users must be added by an administrator.
• Allow unregistered users to run Public
ublic Gallery workflows: When checked,
allows users to run a workflow without signing in to the Gallery.
Page 36
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
•
Chapter 6 Gallery Administration
Default behavior for workflow credentials:
credentials:
• Always run workflows with server or studio default credentials
credential s: All
workflows will run using the Default Gallery Administrator credentials
specified during server configuration or the credentials assigned to the
studio.
• Require users to enter their own credentials when running any
workflow:
workflow: Users will be prompted to enter their credentials when they run
the workflow.
• Allow users to set options
options for credentials when saving a workflow:
workflow:
When saving a workflow, a user will be prompted to specify the
credentials required to run the workflow.
Subscription (Studio) Management
A Subscription is another name for a Studio. A Studio allows Alteryx Designer users to
publish and share workflows privately within their organization.
Each user that creates a Gallery account automatically gets a Private Studio created for
them. When a user creates a workflow in Alteryx Designer and publishes it to the Gallery,
the workflow is added to the user’s Private Studio. Workflows published to the Private
Studio are private and cannot be seen by the general public – they can only be seen by
other users associated with that Studio. Each Studio includes a limited number of user
seats.
Gallery Admins can create studios as well as manage the users and workflows assigned to
them.
Creating a New Subscription
1. Click the Subscriptions option in the left menu.
2. Click Add New Subscription.
Subscription Complete the necessary fields.
• Private Studio Name: The name for the studio, which displays at the top of
the page when the user clicks Private Studio on the left menu of the Gallery
page.
• Contact Name:
Name: The person who owns and manages the studio.
• Subscription Type: Can be either Free or Paid.
• Free:
Free: Artisans and Members who are part of the studio can run
workflows in the Public Gallery.
• Paid:
Paid: Artisans who are part of the studio can publish and run
workflows in that studio and Members can run workflows.
• Artist Seats:
Seats: The number of Artisan seats available in the studio. An Artisan
can publish, run, and share workflows in the studio they have been added to.
Only an Admin can add an Artisan to a studio.
• Member Passes:
Passes: The number of Member seats available in the studio. A
Member can run workflows in the studio they have been added to. Admins can
add a Member to a studio and Artisans can distribute memberships to users.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 37
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
Expiration Date: The date the Paid subscription expires. An expiration date is
required for Paid subscriptions. When the Paid subscription expires it is
downgraded to a Free subscription. All workflows and users will still exist
within the studio but they will not be able to publish new workflows.
• API Enabled: Access to the Private Server Gallery API is disabled by default.
The Gallery API supports the ability to authenticate, list apps, run apps, and
retrieve app results using an API Key and Secret, which are accessible via
Gallery Settings.
• Default Workflow Credentials:
Credentials The workflow credentials used to run the
workflow. Click Set Account to select different credentials.
3. Click Save.
Save
•
The new studio is added to the Subscriptions page. The number of Artisan seats assigned
and the total number of Artisan seats available display in the studio box.
Once a studio has been created, it can be deleted by clicking the trash icon next to the
studio name. Before a studio can be deleted, all users must be removed. Deleting a studio
also deletes the workflows in that studio.
Editing a Subscription
1. Click the Subscriptions option in the left menu.
2. Click the studio name. The Edit Subscription page displays.
3. Make changes and click Save.
Save
Page 38
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
Within this window an Admin can:
•
•
•
•
•
•
Change the name of the studio in the Private Studio Name field.
Change any of the information in the other fields.
Change a subscription from Free to Paid and vice versa.
Add Artisans and Members to the studio. (for Built-in authorization)
Invite users to the studio via an email address. (for Built-in authorization)
Move a user to the studio by copying the Subscription Key and pasting it in
the user’s profile.
Adding a User to a Studio
1. Click the Add Artisan or Add Member button.
2. Start typing the user’s name in the field.
3. If the user already exists, their profile information will display. Click the user
profile to add the user to the Artisan or Member field.
4. If the user does not exist, type their email address. Click the Invite button to invite
the user via an email. The user will need to confirm their email address when they
log in to the Gallery the first time, or the Admin can validate the user’s email
address via the user’s profile.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 39
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
User Management
Gallery Admins can add users directly to the Gallery or they can send an email inviting
users to log in and add themselves via the Join now form on the main page of the Gallery.
User permissions are managed in the user’s profile (or in the Permissions page for
Windows authentication) as well as in the studio the user is assigned to.
Creating a New User
1. Click the Users option in the left menu.
2. Click Add New User.
User Complete the necessary fields.
• Curator:
Curator: A curator is another name for an Admin. Users who are
designated an Admin can access the Admin page.
• Password: An Admin can choose to designate a password for the user. A
password is required if the Gallery Join now form has been disabled since
this prevents the user from designating their own password.
3. Click Save.
Save
The new user is added to the Users page. The user’s name, email address (for Built-In
authentication), and name of the studio they are assigned to display in the user box, as
well as icons that represent their permissions. Once a user has been created, it can be
deactivated but not deleted. If you filter to show inactive users, they will display on the
Users page in gray.
Admin user: Can access the Admin page.
Page 40
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
Artisan: Can publish, run, and share workflows in their studio.
Member:
Member: (for Built-In authentication) Can run workflows in their studio.
Viewer: Can run workflows in the Public Gallery.
Editing a User
1. Click the Users option in the left menu.
2. Click the user’s name. The Edit User page displays.
3. Make changes and click Save.
Save
Within this window an Admin can:
•
•
•
•
•
Change the user’s profile information and image.
Change the user from a non-Admin to an Admin and vice versa.
Change the user from Active to Inactive and vice versa.
Reset the user’s password.
Move the user to another studio by copying the Subscription Key for that
studio and pasting it in the user’s profile.
Resetting a User’s Password
1. Click the Users option in the left menu.
2. Click the user’s name. The Edit User page displays.
3. Click Reset Password.
Password
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 41
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
4. The Reset Password dialog box displays. Click OK.
OK An email is sent to the user
with a link for them to reset their password.
Disabling the Sign-Up Form
1. Click the Users option in the left menu.
2. Click the Disable SignSign-up Form checkbox. When a user clicks Sign In on the
Gallery, the Sign In area will display but the Sign Up area will not. When the SignSignup Form is disabled, new users must be added by an administrator.
Workflow Credentials Management
Gallery Admins can manage how workflows run within the Gallery by setting up default
credentials at the studio level, allowing users to save workflows with specific credentials,
or requiring users to enter credentials to run a workflow.
Creating New Workflow Credentials
1. Click the Workflow Credentials option in the left menu.
Page 42
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
2. Click Add New Credentials
Credential s.
3. Enter the Username and Password and click Save.
Save
Sharing Workflow Credentials
1.
2.
3.
4.
Click the Workflow Credentials option in the left menu.
Click the name of the credentials. The Edit Workflow Credentials page displays.
Click the Users and Studios tab.
Search for and select a user or subscription to share the credentials with.
Permissions Management
Gallery Admins can manage user permissions in the Permissions page when using
Windows authentication.
Setting Default Permissions for New Users
1. Click the Permissions option in the left menu.
2. Click the Default Permission drop down and select one of the following options:
• No Access: Cannot access anything on the site.
• Viewer:
Viewer: Can run workflows in the Public Gallery.
• Artisan:
Artisan: Can publish, run, and share workflows.
• Curator: Can access the Admin page.
Setting Permissions for Users and Groups
1. Click the Permissions option in the left menu.
2. Type the name of the user or group in the Search field. Select the user or group
name.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 43
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
3. The Add Permission dialog box displays. Select the permission type and click OK.
OK
4. The user is added to the Permissions page. Click to edit or delete the user
permission.
Workflow Management
Gallery Admins can add workflows, apps, and macros to the Gallery and manage the Run
Mode settings and exemptions. Admins can also create tags and associate the tags to
workflows so searches return better results and similar workflows can be grouped into
districts.
All workflows, apps, and macros can be published to the Gallery, shared with users, and
downloaded and opened within Designer. Only workflows and apps can be run via the
Gallery.
Adding a Workflow
1. Click the Workflows option in the left menu.
2. Click Add New.
New
3. The Upload a new workflow dialog box displays. Browse to the workflow, select
it, and click OK.
OK The workflow must be packaged as a .yxzp file to be uploaded.
Page 44
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
4. Click OK.
OK The Workflow Validation dialog box displays.
5. Click Close.
Close
The workflow is added to the Workflows page. The user’s name, the name of the studio
the workflow is in, and the date display.
Adding a Tag
1. Click the Workflows option in the left menu.
2. Type the tag in the Tag field and click Add New.
New
• Admin Only: Tags created with this option selected are only available for
an Admin to use when tagging workflows.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 45
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
Editing a Workflow
1. Click the Workflows option in the left menu.
2. Click the name of the workflow. The Edit Workflow page displays. Modify the
workflow’s description, add a tag, or change the icon image, and click Save.
Save
Within this window an Admin can also modify the following:
•
Run Mode: Determines the level that workflows are permitted to run in the
Gallery. Workflows that contain certain tools or access may need to be
blocked. The Default Run Mode is selected when the server is configured. If a
user has a workflow that uses one of the prohibited tools in a safe manner,
they may request an exemption so it can be run in the Gallery and the Run
Mode option can be changed for that specific workflow.
• Unrestricted: Any workflow can be run.
• SemiSemi -safe: Workflows accessing or storing data on non-local drives
will be blocked from running.
• Safe: Workflows accessing or storing data on non-local drives, or using
certain tools and events, will be blocked from running. The tools and
events include: Run Command tool, Download tool, Email tool, R tool,
Run Command event, and Send Email event.
Safe and Semi-safe options can only be used if the Worker > Run As setting
has been enabled.
•
•
Page 46
Requires Private Data: Indicates if the workflow requires licensed data to
run.
Private Data Exemption: An exemption can be given to a workflow with
private data so that it can run.
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
Notification Management
The server can send email notifications for various events such as registering your Gallery
account, changing your password, or sharing a workflow, and Gallery Admins can manage
the types of notifications and the message text. To enable email notifications, enter the
SMTP server information on the Gallery > SMTP screen in the server configuration
windows. The following list includes the notifications available.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Workflow added to collection
Workflow updated in collection
Collection shared with user
Membership granted
Artisanship granted
Workflow shared in public gallery
Curator created a new license user account
Curator created a new user account
License created
Membership expired
Membership revoked
Validation email
Password changed
Password reset
© 2016 Alteryx, Inc.
v1.6, May 2016
•
•
•
•
•
•
•
•
•
•
•
•
•
Pending user workflow added to
collection
Pending user collection updated
Pending user invited to a collection
Pending user granted membership
Pending user granted artisanship
Referral
Profile completed
Workflow shared link
License created notification
Curator created new active user account
Collection sharing grated
Collection sharing revoked
Collection cleanup error
Page 47
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
District Management
Districts provide the ability to group and categorize the workflows that are shared in the
Gallery so that users can easily locate them. Gallery Admins can create new districts and
modify the district name, description, and icon image. Once the District has been created,
it displays on the Districts page in the Gallery.
Creating a District
1. Click the Districts option in the left menu.
2. Click Add New.
New Complete the necessary fields.
• Title:
Title: The title that displays on the district page.
• Nav Link:
Link : Clicking the link opens the district page with all associated
workflows.
• Tag: The tag associated with the district. The drop-down list displays all
tags that have been created by the Admin. Only workflows associated with
the same tag will display on the district page.
• Description: Additional text that displays on the district page and
provides more information about the workflows in the district.
4. Click Save.
Save
Media Management
Gallery Admins can upload banner ads and other images and files to add to the site.
1. Click the Media option in the left menu.
• Click the Banner Ads link and the Add New button and choose an image file.
• Click the Uploads link and the Upload A File button and choose a file.
Page 48
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 6 Gallery Administration
Theme Management
Gallery Admins can brand the Gallery with their organization’s name, logo, and colors.
1. Click the Theme option in the left menu.
• Type the company name in the Gallery Name field and click Save.
Save
• Click Upload a logo.
logo The Upload a new logo dialog box displays. Click Browse
and select an image file.
• Click a color box and select a color for the Header, Body, Navigation, Footer,
Search, and Button elements and click Save.
Save
2. Refresh the Gallery page and the new name, logo, and colors display.
Page Management
Gallery Admins can create new pages to add to the site.
1. Click the Pages option in the left menu.
2. Click the Add New button. Complete the necessary fields.
• Title:
Title: The title of the page.
• Permalink: A direct link to the page generated based on the title.
• Status: The page can be either a Draft or a Published page.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 49
Chapter 6 Gallery Administration
Alteryx Server Installation and Configuration Guide
• Body:
Body: The text that displays on the page.
5. Click Save.
Save
Link Management
Gallery Admins can add links to new pages to the site.
1. Click the Links option in the left menu.
2. Select a page from the drop-down list to create a link in the Header or Footer of
the site.
3. Click Add New.
New
A link to the new page displays when hovering over the More icon in the Gallery
header.
Page 50
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 7 Troubleshooting
Chapter 7 Troubleshooting
This section describes suggested steps for resolving issues that may be encountered
when installing, licensing, or configuring Alteryx Server. If you have additional questions
or need further assistance, please call Client Services at: 888-255-1207.
My workflows are always in a “Queued” state when scheduled or during
validation.
You may be encountering this issue if the Worker machine has not been configured to
run scheduled workflows. Double-click the System Settings icon on your desktop to open
the System Settings window and check the following settings:
In a singlesingle-machine deployment:
• Ensure the machine has been configured to have the Worker enabled. The Worker
is enabled if any of the following options on the Environment > Setup Type
screen are checked:
Designer and Scheduler Only
Complete Alteryx Server
Custom: Enable Worker
• Verify the machine is set up to execute scheduled workflows. On the Worker >
General screen, ensure the Allow machine to run scheduled Alteryx workflows
workflows
option is checked.
• Verify the Quality of Service option on the Worker > General screen is set to 0.
In a multimulti -node deployment:
• Ensure you have at least one machine in the deployment configured to act as a
Worker.
• If the Worker is connecting to a remote Controller, verify it is connecting to the
correct controller. On the Controller > Remote screen click Test to verify it can
connect successfully.
• Verify the Worker machine is set up to execute scheduled workflows. On the
Worker > General screen, ensure the Allow machine to run scheduled Alteryx
workflows
workflows option is checked
Maps in the Map Input, Report Map, and Map Question tools don’t show up.
You may be encountering this issue if the Worker machine has not been configured to
render map tiles, or if the number of processes to be used for tile rendering needs to be
increased. Double-click the System Settings icon on your desktop to open the System
Settings window and check the following settings:
In a singlesingle-machine deployment:
• Ensure the machine has been configured to have the Worker enabled. The Worker
is enabled if any of the following options on the Environment > Setup Type
screen are checked:
Designer and Scheduler Only
Complete Alteryx Server
Custom: Enable Worker
• Verify the machine is set up to render map tiles. On the Worker > Mapping screen,
verify that the Allow machine to render tiles for mapping option is checked.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 51
Chapter 7 Troubleshooting
•
Alteryx Server Installation and Configuration Guide
Verify the Max number of render workers
workers option on the Worker > Mapping
screen is set to a value greater than 0. The default value is 2.
In a multimulti -node deployment:
• Verify that you have at least one machine in the deployment configured to act as
a Worker.
• If the Worker is connecting to a remote Controller, verify it is connecting to the
correct controller. On the Controller > Remote screen click Test to verify it can
connect successfully.
• Verify the Worker machine is set up to render map tiles. On the Worker
Worker > Mapping
screen, ensure the Allow machine to render tiles for mapping option is checked.
• Verify the Max number of render workers option on the Worker > Mapping
screen is set to a value greater than 0. The default value is 2.
• On the Controller machine, ensure the Enable map tile controller option is
selected on the Controller > Mapping screen.
I have configured Alteryx Server to run workflows as a specified user, but they are
failing.
You may be encountering this issue if the Worker machine that is configured to run the
workflows as a specified user does not have the appropriate permissions in the
workspace folder where files are stored. Double-click the System Settings icon on your
desktop to open the System Settings window and check the following settings:
•
•
•
•
•
Identify the Workspace folder specified on the Worker > General screen.
Open Windows Explorer and navigate to that folder.
View the folder properties.
On the Security tab, verify that the user specified as the Run As user exists in the
list of users. If it does not, add it.
On the same tab, highlight the specified user and ensure it has the following
permissions: Modify / Read & Execute / Read / Write.
I need to temporarily shut down Alteryx Server.
Once Alteryx Server has been installed, you can safely shut down the service by following
these steps:
1.
2.
3.
4.
Click the Windows Start button.
Type ‘services.msc’ in the Search field and press Enter.
Enter
In the Services window, locate and select Alteryx Service in the list of services.
Click the Stop link to stop the service.
You may need to refresh the list of services to confirm the Alteryx Service has stopped
and it may take up to 30 seconds for Alteryx Server to completely shut down.
Page 52
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Chapter 8 MongoDB Backup and Restore
Chapter 8 MongoDB Backup and Restore
Alteryx includes an option to use an embedded version of a MongoDB database when
setting up a Gallery to reduce the amount of configuration necessary for deploying a
basic instance of Alteryx Server.
Several utilities are available to backup and restore data from Alteryx Server
deployments, which can prove beneficial in the unlikely event of a system failure, data
corruption or loss, or need to roll back to past data.
The process for creating backups and restoring data can be done through command line
utilities available from the AlteryxService.exe executable.
The database backup process requires Alteryx Server be shut down, disabling Scheduler
and Gallery functionality for several minutes, so it is recommended that backups are
performed during off-peak times.
Creating a Backup
1. Stop AlteryxService.
2. From the command line, navigate to the directory to store the backup.
3. Execute the following command to save a backup of the database in the specified
folder:
alteryxservice emongodump=<path to backup location>
W:\Alteryx\bin\AlteryxService.exe emongodump=“c:\temp\dumpOutput”
Restoring from a Backup
1. From the command line, navigate to the directory where the backup is located.
2. Execute the following command to take the saved backup from the output folder and
move it to the specified input folder:
mongorestore --dbpath=<path to mongo folder> <path to backup location>
W:\Alteryx\bin\AlteryxService.exe
emongorestore=“c:\temp\dumpOutput”,”c:\temp\restoreInput
3. Restart AlteryxService.
Using a Backup
1. Open the System Settings window.
2. Go to Controller > Persistence.
Persistence
3. In the Data Folder field, click the Browse button to browse to the folder for the backup.
4. Click Next to continue through the System Settings windows and restart the Service.
When the Service starts it will run off the restored folder.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 53
Appendix
Alteryx Server Installation and Configuration Guide
Appendix
Enabling SSL for Alteryx Server
Alteryx Server supports SSL (Secure Socket Layer) encryption via HTTPS to ensure that all
communication between Alteryx Designer and Alteryx Server, as well as between a user’s
web browser and your Alteryx Private Gallery, remains safe and secure.
Before enabling SSL on your machine, obtain a valid SSL certificate for your Alteryx
Private Gallery from a trusted Certificate Authority (CA). The service address that you
specify for the certificate must match the address that you want to use for your Gallery
website domain (the same domain that is specified within the Base Address URL on the
System Settings > Gallery > General screen).
Once you have obtained the SSL certificate, you need to configure your web server to use
that certificate when users visit your site. To do this, the certificate thumbprint must be
associated with a specific port on the machine.
Obtaining an SSL Certificate’s Thumbprint
To obtain the thumbprint of the certificate:
1. Locate and open the certificate (.cer) file.
2. Click the Details tab.
3. Scroll through the list and highlight Thumbprint.
Thumbprint
4. The value displayed in the box at the bottom is the thumbprint of the certificate.
Copy the value, paste it into Notepad, and remove all spaces. This is the value that
will be used when configuring the port.
Page 54
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Appendix
Configuring a Port to Use an SSL Certificate
To associate the certificate’s thumbprint to a specific port:
1. Click Start to open the netsh console, type ‘netsh’ in the Search field, and press
Enter.
Enter
2. Edit the following command.
• Replace the ‘certhash’ value with the certificate thumbprint value without
the spaces.
• Modify the ipport value if you want to use a port other than the default
port 443.
• Leave the appid as it is since it is the application ID of the Alteryx Gallery.
http add sslcert ipport=0.0.0.0:443
certhash=0000000000003ed9cd0c315bbb6dc1c08da5e6 appid={eea9431a-a3d44c9b-9f9a-b83916c11c67}
3. Paste the modified command into the netsh console and press Enter to associate
the certificate with the given port.
4. Verify the association and successful install of the certificate by running the
following command in the netsh console. All SSL certificate associations and their
respective ports will be listed.
http show sslcert
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 55
Appendix
Alteryx Server Installation and Configuration Guide
Configuring the Alteryx Server Gallery URL
Once the certificate has been associated with a specific port, the Alteryx Server
configuration must be changed to expect web requests over HTTPS instead of HTTP.
Additionally, if the certificate has been associated with a port other than the default 443,
Alteryx Server will need to be configured to utilize that port.
1. Double-click the System Settings icon on your desktop.
2. Click Next on each screen of System Settings to navigate through the
Environment,
Environment Controller,
Controller and Worker components.
3. On the Gallery > General screen select the Enable SSL checkbox. Enabling this
option changes the URL in the Base Address field to https.
4. If you enable SSL and your certificate is set to a port other than the default 443,
specify the port in the Base Address URL as well. (e.g.,
https://localhost:445/gallery/)
5. Click Next to continue navigating through the settings for the Gallery and Engine
components and click Done to close the System Settings window and restart
Alteryx Services.
Once the SSL certificate has been installed on the local server machine and SSL has been
enabled in the Alteryx Server System Settings, users who go to the Gallery will see https:
and a padlock symbol displayed before the URL address in their browser. This means that
a secure link is established for that session, with a unique session key, and secure
communications will occur.
Page 56
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Appendix
Installing Alteryx Custom Tool Packages
Alteryx provides several options for creating custom tools. One method for deploying a
custom tool involves packaging the tool and all of its dependencies into a single .yxi file.
When a tool that is packaged as a .yxi file is installed, the tool is added to the tool palette
in Designer and the .yxi file and supporting macros are installed in the AppData\Roaming
folder in the user’s account. For example:
C:\Users\<username>\AppData\Roaming\Alteryx\Tools\<tool name>.
A .yxi file must be manually installed before a workflow that includes that tool can be run.
In order for a tool package to be available to Gallery and Scheduler processes on a
machine, a Gallery administrator must copy the contents of the .yxi file to the
C:\ProgramData\Alteryx\Tools directory on the server. In a multi-node environment, the
.yxi file must be added to every worker machine in your server deployment.
To install a Tool Package on the server:
•
•
•
•
Double-click the .yxi file and select OK on the Tool Installer window.
Locate the user Tools directory: C:\Users\<username>\AppData\Roaming\Alteryx\Tools.
Copy the folder of the tool to be installed on the server.
Paste the folder in the following directory: C:\ProgramData\Alteryx\Tools.
Alteryx loads tools in the Designer from these locations in the following order:
•
•
•
C:\Users\<username>\AppData\Roaming\Alteryx\Tools
C:\ProgramData\Alteryx\Tools
Alteryx install folders
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 57
Glossary
Alteryx Server Installation and Configuration Guide
Glossary
Term
Definition
Admin
A user who has access to the Admin page on the Gallery.
Alteryx Designer
A desktop application that provides an intuitive drag and drop user
interface for authoring and executing analytic applications.
Alteryx Engine
Consumes Alteryx workflows and provides high-speed data
processing and analytics functionality.
Alteryx Gallery
A cloud- or self-hosted application for publishing, sharing, and
executing workflows.
Alteryx Service
A scalable service supporting workflow execution and scheduling. It
uses a Worker-Controller architecture which allows it to be deployed
across multiple servers, where one server acts as the Controller and
the others perform the work.
Artisan
A user who can publish, run, and share workflows on the Gallery.
Authentication Type
Alteryx Server supports a built-in authentication scheme as well as
integrated Windows authentication.
Base Address
The URL that users will use to go to the Gallery. It is also used in the
email content when links to workflows are made available and it is
what the underlying WCF technology will use to see if it needs to
handle requests coming in.
BuiltBuilt -in
A uthentication
Allows users to access the Gallery using an email address and
password.
Controller
Responsible for the management of the service settings and the
delegation of work to the Workers. In a typical deployment, there
would be only one machine enabled as the Controller and it would
be set up to act as a Worker as well.
Controller Token
The secret auto-generated key that is used to configure a Worker
machine to communicate with the Controller machine.
Default Gallery
Administrator
The person who is set up to be the initial Gallery Administrator and
given permission to access the Gallery and manage studios, users,
and workflows. If using Build-in Authentication it is the email
address and password of the site administrator. If using Windows
Authentication it is the user name of a domain user.
Environment
A component of System Settings that includes the settings for
identifying the type of configuration for the machine, as well as a
global workspace for other components to use as a root location for
file storage.
Logging
Information about certain system events, such as services being
started, shut downs, execution requests, etc., are logged and stored
Page 58
v1.6, May 2016
© 2016 Alteryx, Inc.
Alteryx Server Installation and Configuration Guide
Glossary
in files. These logs can be used to help troubleshoot system issues.
Logging is available for the Controller, Worker, and Gallery.
Member
A user who can run workflows in Studios and Collections they have
been added to.
Persistence
A part of the Alteryx Service that stores information critical to the
functioning of the service, such as Alteryx application files, the job
queue, and result data. There are two different persistence
mechanisms: SQLite and MongoDB.
Predictive Tools
A set of tools that use R, an open-source code base used for
statistical and predictive analysis. Selecting to install predictive
tools during the server installation will launch the Alteryx R installer
and install the R program and the predictive tools that use R as part
of the Alteryx Designer.
Quality of Service
The Quality of Service (QoS) setting is used to manage resource
allocation in an environment where multiple workers are deployed
by restricting which jobs will be run by each Worker. The QoS value
for a Worker can be set higher for specific types of jobs to allow the
Worker resource to be reserved for higher priority requests.
Scheduler
Allows users to schedule workflows to execute at predetermined
times or a specific intervals. The Scheduler connects to either a local
or remote instance of the Alteryx Service where the job will be
queued for execution at the appropriate time.
SMTP server
The Server sends out email notifications for various events, such as
registering your Gallery account, changing your password, or sharing
a workflow. To enable email notifications from the Gallery, enter the
From Email, Host, Port, Username, and Password information for your
SMTP server in the server configuration windows. (The From Email,
Host, and Port are required, while Username and Password are only
required if the SMTP server configuration requires it.)
System Settings
The various settings, including the Environment, Controller, Worker,
Gallery, and Engine components that can be configured after the
Alteryx Server has been installed.
Viewer
A user who can run workflows in the Public Gallery.
Windows
Authentication
Allows users to access the Alteryx Gallery with internal network
credentials.
Worker
The Alteryx Service Worker is responsible for executing analytic
workflows. There must be at least one machine enabled as a Worker
in order to execute applications through the Service and you may
configure the same machine to be both the Controller and a Worker.
The actual number of Workers needed will depend upon the
required performance for the system.
© 2016 Alteryx, Inc.
v1.6, May 2016
Page 59
Document History
Alteryx Server Installation and Configuration Guide
Document History
Version Date
Description
v 1.0
April 2014
Initial document.
v 1.1
August 2014
v 1.2
January 2015
v 1.3
April 2015
v 1.4
September 2015
v 1.5
November 2015
v 1.6
1.6
May 2016
Updated with 9.1 changes:
• The licensing process has been improved.
• The “Public Gallery” area has been renamed to “My
Company’s Gallery” and is now customizable.
• Gallery user sign up can be disabled, giving only
administrators the ability to create new users.
• Gallery administrators can deactivate users.
Added instructions for installing a certificate and enabling SSL.
Updated with 9.5 changes:
• References to “module” have been updated to “workflow”
throughout.
• Support for the Gallery API is available via an API Key and
Secret within a Subscription.
• Gallery administrators can tag workflows published to the
Gallery to improve search results.
• Gallery administrators can associate Districts with a tag
to group tagged workflows.
• Macros and workflows can now be published to the
Gallery.
Added instructions for configuring a Worker machine.
Added steps for safely shutting down the Alteryx Service.
Updated with 10.0 changes:
• Added MongoDB migration information.
• Added MongoDB database backup and restore process.
• Updated images throughout.
• Added proxy server support
Updated with 10.1 changes:
• Enabling SMTP settings is no longer required for initial
Server configuration.
• Updated installation window images.
Updated with 10.5 changes:
• Added Kerberos support.
• Gallery administrators can delete subscriptions (studios).
• Gallery administrators can manage how workflows run by
setting up default credentials at the studio level, allowing
users to save workflows with specific credentials, or
requiring users to enter credentials to run a workflow.
• Added steps for using custom tool packages.
Page 60
v1.6, May 2016
© 2016 Alteryx, Inc.