Server Host Recovery Guide

1.1

Set host time zone

The Windows time zone of the target host must be set to match the original host.

1.2

Ensure access to Alteryx

Ensure the host can contact whitelist.alteryx.com used by the Alteryx licensing system.

3.1

Open Command Prompt 1 in bin folder

Open a Command Prompt As Administrator and navigate to the Alteryx\bin folder, enter the commands below (adjust based on your install location).

c: 

cd \Program Files\Alteryx\bin 

3.2

Stop the Service

Enter the command

net stop alteryxservice 

On success you should see "The AlteryxService service was stopped successfully."

3.3

Backup existing RuntimeSettings.xml

Enter the command

c: 

cd \ProgramData\Alteryx ren RuntimeSettings.xml RuntimeSettings_BACKUP.xml 

3.4

Do you have a RuntimeSettings.xml previously prepared on your target host from a Disaster Recovery Preparation?

YES: Your RuntimeSettings.xml from the Disaster Recovery Process should already be located in your target host’s %ProgramData%\Alteryx\ directory. If not, copy the prepared RuntimeSettings.xml to %ProgramData%\Alteryx\.

Go to step 3.13.

NO: Copy the RuntimeSettings.xml file from your original host to the current target host's %ProgramData%\Alteryx\ directory.

Continue to step 3.5.

3.5

Clear Controller Token

Edit the RuntimeSettings.xml you just copied and delete everything between the <ServerSecretEncrypted> tags, leaving just the tags as shown below:

Save and close the file.

3.6

Restore Controller Token

Enter the command using your original server Controller Token

AlteryxService.exe setserversecret=CONTROLLER_TOKEN_FROM_ORIGINAL_SERVER 

Troubleshooting:

Version 2021.3+ can error on this step with: "Set server secret failed: Error in CryptImportKey(3): Bad Data. (-2146893819)". To correct this, see the previous step to ensure the value was removed from between the tags.

3.7

Restore Storage Keys Encrypted

The <StorageKeysEncrypted> value might have changed when the controller token was reset in step 3.6. If so, it should be replaced with the corresponding value from the original RuntimeSettings.xml file. This is the source RuntimeSettings.xml file that was copied in step 3.4. It is easiest to copy the tags as well to ensure that the entire value between them is copied from the original RuntimeSettings.xml file. You can leave RuntimeSettings.xml open in a text editor as you make further changes in step 4.

3.8

Restore Run As User

If you had a Run As User on the original host, enter the following command, otherwise skip this step.AlteryxService.exe setexecuteuser=NAME,DOMAIN,PASSWORD

3.9

Restore SMTP Password

If you had filled in Alteryx System Settings > Server UI > SMTP > Password (even if the SMTP checkbox was unchecked), enter the following command, otherwise skip this step.AlteryxService.exe setsmtppassword=PASSWORD

3.10

Save RuntimeSettings.xml

Save the RuntimeSettings.xml file.

3.11

Is the version of Alteryx Server on your original host any of the following versions?

YES: Go to step 3.13.

NO: Continue to step 3.12.

3.12

Transfer Encryption Key

This functionality is only available on the following versions:

Important: Please note that this requires the AlteryxService to be running on your original host and your target host will need to be able to access it over the network.

The steps in Encryption Key Transfer Process will allow you to transfer the encryption key from your existing controller to your new one.

3.13

Remain on the Command Line

Step 4 assumes you are in an Administrator command line in the  \Alteryx\bin folder.

4.1

Get MongoDB backup

Copy the Mongo backup from the original host to a MONGO_BACKUP folder on your new host.

4.2

Restore to a new folder

Restore the Mongo database from the backup folder to a new restore folder. Review mongoRestore.log as described below to ensure the restore was successful.

Refer to the Restore from a MongoDB Backup section in the MongoDB Backups document to find the appropriate restore command for your Server version.

4.3

Confirm the restore was successful

Confirm the restore was successful.

Caution 

This is a necessary step as a restore failure will not be reported in the previous step and can lead to missing data on your Server. To do so, review the mongoRestore.log file in the MongoDB folder where the data was restored. Open mongoRestore.log and follow these steps:

If the recovery has failed, or if you find any results when searching the key words listed above, please contact Customer Support with all the information you have gathered.

Do not proceed if the MongoDB restore failed. 

4.4

Set Mongo path in RuntimeSettings.XML

Edit RuntimeSettings.xml and enter the path to the MONGO_RESTORE_FOLDER in the <EmbeddedMongoDBRootPath> tag.

Example:

Save and close the text editor.

4.5

Start MongoDB

Enter the command

mongod ––dbpath "MONGO_RESTORE_FOLDER" ––auth ––port 27018 

Example

mongod ––dbpath "%ProgramData%\Alteryx\Service\Persistence\Mongo_Restore" ––auth ––port 27018 

Do not close the command prompt window.

If you close the window from step 4.5, none of the subsequent steps will work.

<< Begin second Command Prompt section >> 

4.6

Open second Command Prompt in bin folder

Open a SECOND Command Prompt As Administrator and navigate to the Alteryx\bin folder, enter the commands below (adjust based on your install location).

c: 

cd \Program Files\Alteryx\bin 

4.7

Get Non-Admin Mongo password

Enter the command and copy your NON_ADMIN_MONGO_PASSWORD to Notepad

AlteryxService.exe getemongopassword 

4.8

Start Mongo Command Line

Enter the command

mongosh mongodb://SERVER:PORT/AlteryxGallery -u user -p NON_ADMIN_MONGO_PASSWORD 

Example

mongosh mongodb://localhost:27018/AlteryxGallery -u user -p CCEC***33C0 

On success you should see a ">" prompt.

4.9

Delete AlteryxGallery locks set by original Server

Enter the Mongo command

db.locks.remove({}) 

On success you should see: "writeResult({ “nRemoved” : N })", where N is a number between 0 and 3.

4.10

Switch to AlteryxService database

Enter the Mongo command

use AlteryxService 

4.11

Delete AlteryxService locks set by original Server

Enter the Mongo command

db.locks.remove({}) 

On success you should see: "writeResult({ “nRemoved” : N })", where N is a number between 0 and 3.

4.12

Quit Mongo Command Line and Command Prompt 2

Enter the command

exit 

Close Command_Prompt_2

<< End second Command Prompt section >>  

4.13

Stop Mongo database

In the original command prompt, enter the keyboard command

ctrl-c 

one or more times until you exit MongoDB and return to a normal command prompt.

Close the command prompt.

5.1

Did you have a Service Log On User on the original Server?

Set Service Log On User on new Server.

Windows Services app > right-click AlteryxService > Properties > Log On

5.2

Add data drivers and System DSNs.

Add same-version drivers and same-name System DSNs to match original Server, https://downloads.alteryx.com/.

Advanced issues that may not apply to your recovery: 

5.3

In more secure environments, configure required Run As user permissions.

Ensure all credentials used to run workflows (Run As, Service Log On, or credential set when saving the workflow) have proper sufficient access, configure required run user permissions.Configure Required Run As User Permissions

5.4

Restore System-based and In-DB Connection Aliases

System Data Connections:

%ProgramData%\Alteryx\Engine\SystemAlias.xml   

System In-DB Data Connections:

%ProgramData%\Alteryx\Engine\SystemConnections.xml   

5.5

Restore User-Based and User In-DB Connection Aliases

User Data Connections:

C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserConnections.xml   

User In-DB Data Connections:

C:\Users\[username]\AppData\Roaming\Alteryx\Engine\UserAlias.xml   

5.6

Do workflows use Connectors?

Copy Connector folders from your original server to

%ProgramData%\   Alteryx\Tools 

Contact Customer Support to enable Connectors on your new Server.

5.7

Do workflows use the Python Tool?

Re-install any Python packages that workflows had installed. See Python Tool Environment in Server Upgrades.

5.8

Do you use SSL?

If you are recovering to a Sandbox Server for testing, use HTTP for testing.

If you are migrating to a new Server, re-establish your SSL:

Configure Server SSL/TLS 

Configuring Alteryx Server for SSL Obtaining and Installing Certificates 

6.1

Review Alteryx System Settings, suspend Schedules if desired.

Run Alteryx System Settings and step through each page confirming the settings (like the Controller Token) contain the values you expect.

If you do not want Schedules to run when the Service starts, uncheck:

Worker > General > Allow machine to run scheduled Alteryx workflows

When you select Finish,the AlteryxService should start and the Server should be available in a browser.

7.1

Basic testing

Is the AlteryxService running?

Can you:

7.2

Workflow-specific testing

Can you run workflows that contain extensions or external connections, such as