Alteryx Server Host Recovery Guide

Version:
2019.3
Last modified: November 21, 2019

This guide is intended to assist an Alteryx Server administrator with recovering an Alteryx Server instance in the event of failure of an original host or hosts.

In Scope

  • Recovery from the failure of a single, default Alteryx Server installation using embedded MongoDB.
  • Available backup with necessary information intact.
  • The target machine(s) can be overwritten.

Out of Scope

  • Multi-node Alteryx Server environment or user-managed MongoDB - please contact customer support for help.
  • Merging of databases of connection files.
  • Back up or restoration of ODBC drivers.
  • Back up or restoration of User or system DSNs.
  • Back up or restoration of other aliases stored in Windows that exist outside of Alteryx.

Prerequisites

  • Install all database drivers and necessary software for workflow operation before completing the steps outlined in this guide to ensure minimal downtime.
  • Administrator rights on the target server.
  • Access to all credentials used for impersonation including, the service account (if not Local System), the Run As user, and any defined/used workflow credentials.
  • Controller Token from the original server.
  • RuntimeSettings.xml from the original server found here: %PROGRAMDATA%\Alteryx\RuntimeSettings.xml.
  • Backup of MongoDB from the original server. Learn how to perform a backup.
    • For more information on Alteryx Server Backup & Recovery, please see the Alteryx Server Backup & Restore Best Practices: Part 1 and Part 2.

Optional

The following items may not have been leveraged in the original Server. Check if the functionality was used and complete the corresponding steps marked (Optional) in this guide.

  • Run-As User details for Worker configuration:
    • Domain
    • Username
    • Password
  • SMTP server username and password for Gallery configuration.
  • Alteryx System-based and In-DB Connection aliases from the original server.
    • System In-DB Data Connections see: %PROGRAMDATA%\Alteryx\Engine\SystemConnections.xml
    • System Data Connections see: %PROGRAMDATA%\Alteryx\Engine\SystemAlias.xml
  • Alteryx User-based and In-DB Connection Aliases from the original server – the below may be relevant for each run-as or Workflow Credential user account
    • User Data Connections see: %APPDATA%\Alteryx\Engine\UserConnections.xml
    • User In-DB Data Connections see: %APPDATA%\Alteryx\Engine\UserAlias.xml

Step 1. Stand Up a New Server

Encrypted items are handled on a per-machine basis via the Windows Crypto API. The following recovery steps must be completed in the exact order presented to ensure a successful recovery of encrypted passwords in the XML and database entries. Complete all steps below on the target server.

  1. Install Alteryx Server on the target server. Ensure it is the same version as the original Alteryx Server.
  2. Open Command Prompt > Run as administrator. You must be an administrator on the target server for this option to be available.
    Elevated Command Prompt
  3. Stop the Alteryx Service on the target server if it is running. Verify the service has stopped before proceeding with further steps.
    • Command:
      net stop alteryxservice
      command-net-stop-alteryxservice
  4. Navigate to the Alteryx installation directory (Default: %ProgramFiles%\Alteryx\bin).
    • Command:
      cd %ProgramFiles%\Alteryx\bin
      command-alteryx-installation-directory
  5. Restore the MongoDB backup to an empty folder on the target server.
    • Command:
       AlteryxService.exe emongorestore=<path to backup location>,<path to restore to>
    • Example: 
      AlteryxService.exe emongorestore=D:\MongoBackups\2019-08-26”,”D:\ProgramData\Alteryx\Service\Persistence\MongoDB_Restore”
      command-restore-mongodb
    • Record the target location of the restore for use in later steps.
  6. Restore the RuntimeSettings.xml from the previous machine to the target machine directory (%PROGRAMDATA%\Alteryx). Overwrite any current file if it exists.
    • (Optional) If a RuntimeSettings.xml file currently exists in the %PROGRAMDATA%\Alteryx folder, make a copy before overwriting the file.
  7. (Optional) Restore the system-wide Alteryx and In-DB Connection alias files as described in the requirements. Restore to the same locations as listed in requirements
  8. (Optional) Restore the user-based Alteryx and In-DB Connection alias files described in the requirements. Restore to the same locations as listed in requirements
  9. In the Administrative command prompt, change directories to the Alteryx Server installation path (Default: %ProgramFiles%\Alteryx\bin).
    • Command:
      cd %ProgramFiles%\Alteryx\bin
  10. Set the Controller token to the value from the original server.
    • Command:
      AlteryxService.exe setserversecret={ControllerTokenValue}
  11. (Optional) If you had a Run-As User set in Alteryx System Settings on the original server, execute the following command to set the Run-As user and password:
    • Command:
      AlteryxService.exe setexecuteuser=name,domain,password
  12. (Optional) If the Gallery is enabled and you had an SMTP server set with a specific password in Alteryx System Settings on the original machine, execute the following command to set the SMTP password:
    • Command:
      AlteryxService.exe setsmtppassword=password
  13. Replace the <StorageKeysEncrypted>{value}</StorageKeysEncrypted> in the RuntimeSettings.xml file (%ProgramData%\Alteryx\RuntimeSettings.xml) with the same from the backup RuntimeSettings.xml file.
    storage-keys-encrypted
  14. Replace the <EmbeddedMongoDBPath>{Path}</EmbeddedMongoDBPath> in the RuntimeSettings.xml file (%ProgramData%\Alteryx\RuntimeSettings.xml) with the target location from Step 5.
    Replace the <EmbeddedMongoDBPath>{Path}</EmbeddedMongoDBPath> in the RuntimeSettings.xml file (%ProgramData%\Alteryx\RuntimeSettings.xml) with the target location from Step 5.
  15. Open Alteryx Designer on the new machine and activate the license(s) if necessary. Close Designer.
  16. Open Alteryx System Settings and step through each page in the System Settings. Confirm all settings are set as intended, including: verify the Controller Token, any passwords set for settings such as the Run-As user, and SMTP password. After confirming the settings, select Finish to start the AlteryxService.
  17. Confirm that the Service started.
    AlteryxService

Step 2. Restore the MongoDB Database

The restored MongoDB database on the new server will likely reference the old server hostname, causing issues with Gallery indexing. Failure to perform the steps below will prevent users from seeing newly published workflows or other changes to the Gallery.

  1. Execute the following command to retrieve the MongoDB connection password:
    • Command:
      AlteryxService.exe getemongopassword
      command-retrieve-mongodb-pwd
  2. Connect to the MongoDB database using the command and connection string below:
    • Command:
      mongo mongodb://{server}:{port}/{galleryDatabase} -u user -p {Non-Admin Password}
    • Example:
      mongo mongodb://localhost:27018/AlteryxGallery -u user -p CCEC733EDBFAE49C8CF96FDAAE520B6A91F233C0
      command-restore-mongodb
  3. Activate the AlteryxGallery database in the MongoDB shell.
    • Command:
      use AlteryxGallery
      command-activate-mongodb
  4. Remove the records from the locks collection in the AlteryxGallery database.
    • Command:
      db.locks.remove({})
    • After executing the command, you should see a result similar to “writeResult({ “nRemoved” : N })”, where N is a number between 0 and 2.
      command-remove-locks
  5. Type the following command to exit the MongoDB shell:
    • Command:
      exit

Congratulations, the host recovery process is now complete! Follow the steps below to confirm that your host recovery was successful.

Step 3. Confirm Host Recovery

We recommend you perform an Alteryx Gallery indexing test and a test of Alteryx Gallery Workflow Credentials to determine that your host is successfully recovered. 

Gallery Indexing Test

Start by verifying a newly uploaded workflow appears. To do so, follow the steps below.

  1. Open Alteryx Designer on a client machine.
  2. Create a workflow. Unless you wish to test specific database connections or functionality, your test workflow can be as simple as a Text Input. Database testing is outside the scope of this guide.
  3. Select File > Save As in Alteryx Designer, then choose the appropriate Gallery connection of the new deployment.
    • If the new Gallery does not appear in the list, choose Add a Gallery and follow the instructions to log in.
  4. Save the workflow with a unique name that you will be able to identify to verify the test is successful.
  5. Enter the Gallery URL directly in a web browser. Sign in with the same Alteryx Gallery account that you used to save the workflow.
    • Note: Do not use the View In Browser button shown after saving – this will not adequately test the functionality.
  6. Select Private Studio and look for the workflow you just uploaded. 
    workflow-index-test
    • If you are unable to locate the workflow, try the following:
      1. Search for the unique name of the workflow you uploaded in the search bar at the top of the page.
      2. Try sorting the view by Latest to see if the workflow appears.
      3. Confirm you have completed all the steps process above, specifically the restoration of the MongoDB Database.
      4. Contact Alteryx Customer Support for help.

Test Alteryx Gallery Workflow Credentials

Testing steps for Alteryx Gallery Workflow Credentials will depend on the Credentials setting within the Alteryx Gallery Admin panel. 

To access the Gallery Admin interface, select your username in the upper-right corner of the Gallery and choose Admin from the drop-down. Select Credentials on the left side of the page. Follow the steps below based on the setting Credentials setting for workflows.

If the Credentials setting for workflows is Use Default Credentials and there are no credentials displayed on the page, no verification is necessary.

If the Credentials setting for workflows is Use Default Credentials and there are credentials displayed, you may have a Subscription/Studio that uses a default credential option.

  1. To test, have a user with access to this studio verify that the workflow(s) execute. Note that even though a credential may not be shared directly with a studio, it can still be set as a default. If the workflow test errors, reach out to Alteryx Customer Support for help.

If the Credentials setting for workflows is Require User Credentials, one or all the below scenarios may apply. 

  1. You may have a Subscription/Studio that uses a default credential option.
    • To test, have a user from one of these studios verify that the workflow(s) execute. Note that even though a credential may not be shared with a studio, it can still be set as a default. If the workflow test errors, reach out to Alteryx Customer Support for help.
  2. You may have one or more user(s) who saved the credentials upon workflow execution via the Make these my default credentials option.
    saved-workflow-credentials
    • To test, have the user execute a workflow with default credentials and confirm the workflow runs. If the workflow test errors, reach out to Alteryx Customer Support for help.
  3. You may have users that have access to Workflow Credentials.
    • To test, confirm users can execute workflows with at least one credential created before the host recovery procedure. If the workflow test errors, reach out to Alteryx Customer Support for help.

If the Credentials setting for workflows is Allow users to select credentials, confirm all test scenarios as described above. Reach out to Alteryx Customer Support for help if any workflow tests error.

Was This Helpful?

Need something else? Visit the Alteryx Community or contact support.