Overview#
Many users will at some point find that they need to move Reportworq to a new location. The following steps will help successfully migrate Reportworq to a new server without losing the users created jobs.
Steps#
These steps move Reportworq and retire the old server. If the old server keeps running, for example when you clone production to make a test server, follow If the old copy stays running instead.
- If the old server is being retired, release the license on it before you copy.
- Make a note of the Reportworq version shown in the footer of the old server, and of the Logon Account used for the Reportworq Bootstrapper Service in Windows Services.
- Stop the Reportworq Bootstrapper service on the old server, so that nothing changes the repository while you copy it. Then set its Startup type to Manual or Disabled, so that a restart of the old server cannot bring it back alongside the new one.
- Copy the repository folder from the old location. It should be located in a similar location to the default C:\Program Files\Reportworq\Repository
- Navigate to the new machine/location to install.
- Install the same Reportworq version that the old server runs, as described on the Installation page. Do not upgrade as part of the move. (Upgrading Reportworq also describes a Full Installation Upgrade for moving to a different server, which installs the newest version; this page keeps the move and the upgrade as separate steps.) If that version is not offered for download, contact Reportworq Support.
- Go to Services.
- Stop the Reportworq Bootstrapper
- Edit properties to insert the correct logon if not using Local System Account
- Navigate to the Installation Directory
- Delete the Repository folder that was automatically created.
- Replace the repository folder with the copy taken from the old machine.
- Before you start the service, clear the copied license identity from the copied repository.
- Start the Service.
- Log on, activate the license and set the Web App Host.
- Verify that everything is working properly.
- If you want a newer version, upgrade the new server now, as a separate step.
Note that if Report Templates used for Reportworq were stored locally on the old machine, then those files should be moved to the new server.
What moves with the repository, and what should not#
The repository holds most of what Reportworq stores about your installation. Three settings stay outside it, in the Reportworq Bootstrapper settings of each server: the Web Server Port, the SSL Certificate and the Repository Path. Check them on the new server after the move.
The repository also holds a License folder with the old server's license identity. That identity is built from two files: identifier.dat, which records a machine name, and record.dat, a random value. Reportworq takes the machine name from identifier.dat, not from the server it runs on. So a repository copied as it is still validates, but as the old server: the new server reports the old machine name, and at startup it re-activates the license as the old server. The two servers then count as one installation. Clearing these files gives the new server an identity of its own.
The repository also holds the Web App Host setting. After the copy it can still name the old server; only when it is blank does Reportworq use the name of the machine it runs on. Either way, set it to the new server's address. Reportworq builds these addresses from it: webhook trigger URLs, the Host Status page, the links in contribution notification emails, and, on load balancer nodes, the address of the job queue and the event hub.
Both are fixed with a few extra steps, done in the order below.
Before you copy: release the license on the old server#
If the old server is being retired, release its license so the seat is returned. If the old server keeps running, do not release: Release removes the license from the server you select it on, so that server stops being licensed. Release contacts the Reportworq license server, so the old server needs internet access.
- Sign in to the old server as a system administrator and select the license message in the lower right corner of Reportworq. The Edit Reportworq License pane appears.
- Select the lock icon to reveal the License Key, and make a note of it. You need it to activate the new server.
- Select Release.
If the old server has no internet access, do not select Release. Release still removes the license from the old server, but the seat is not freed, and Reportworq 5 has no manual release. Note the License Key and contact Reportworq Support so the seat can be freed.
If the old server is already gone and you could not release the license, contact Reportworq Support so the seat can be freed.
To go back to the old server. Apart from the release, the move does not change the old server's repository. Set the old server's Reportworq Bootstrapper service Startup type back to Automatic, start the service, and activate the license again with the key you noted in step 2. If your key allows a single installation, that activation can fail while the new server holds the seat: release the license on the new server first, or contact Reportworq Support.
Clear the copied license identity#
Do this on the new server after you replace its repository folder with the copy and before you start the service. The service must be stopped: do not edit the repository while Reportworq is running against it.
In the repository folder you just put in place, open the
Licensefolder (for exampleC:\Program Files\Reportworq\Repository\License).Delete these files:
File What it holds identifier.datThe machine name that the license identity uses: still the old server's name in a copy. Reportworq writes it again, with the new server's name, the next time it starts. record.datA random value that is combined with the machine name. Reportworq generates a new one, so two copies of the same repository never share an identity, even if their server names match. license.datThe activated license. It is encrypted with the old server's identity, so Reportworq cannot read it once identifier.datandrecord.datare gone.license-metadata.jsonCached license details, including the old machine name. license-metrics.encCached license usage details. You might not see every file. Delete the ones that are there.
Keep
enterprise.licenseif the folder contains it. An enterprise license file is not tied to a particular server, so it needs no re-activation and you can skip the next section.
If you already started the new server on the copy without these steps, it has activated as the old server. Stop its Reportworq service, delete the files above, start the service again, and activate the license.
Activate the license on the new server#
- Start the Reportworq service on the new server and sign in as a system administrator.
- Select the license message in the lower right corner of Reportworq. The Edit Reportworq License pane appears.
- Enter your License Key and select Activate. If the server has no internet access, use Manual Activation... instead. Both are described under Activate License.
Set the Web App Host to the new server#
- In the Administration interface, open Configuration and find the Web Server settings.
- Set Web App Host to the machine name, IP address, or DNS name that other machines use to reach the new server.
- Select Save Changes. If you also changed other Web Server settings, select Restart to restart the Reportworq service.
See Web App Host for what the setting does.
Verify the new server#
- The license message in the lower right corner shows a valid license, and the Edit Reportworq License pane lists the features you expect.
- Run a job and check that it completes.
- Open a webhook trigger URL, the Host Status page, or a link in a contribution notification email, and check that it uses the new server's address.
If the old copy stays running#
If you copied a repository to make a second server, for example a development or test server cloned from production, and the original keeps running, do not release the original's license. Release removes the license from the server you select it on, so the original would stop being licensed.
The copy brings every job and schedule with it, and starts running them as soon as it starts. The pause holds jobs only: writeback and contribution work are not paused. The pause is saved in the repository, so a copy taken while the original is paused starts paused.
- On the original, pause job execution with a duration of 0 (until resumed).
- Stop the original's Reportworq Bootstrapper service and copy the repository folder.
- Start the original's service, sign in, and select Resume in the footer.
- On the copy, install the same Reportworq version and put the copied repository in place, as in Steps. Then:
- Clear the copied license identity before you start it for the first time. Otherwise it presents the original server's identity, and the two servers appear as one installation.
- If the original uses Writeback, contribution campaigns or the Cloud API, contact Reportworq Support before you start the copy. The pause does not hold these, and the copy could act on production's writeback mailbox and campaigns.
- Start the copy's service, activate its license, and set its Web App Host to its own address. Each running copy is activated on its own and may use an installation seat.
- Disable the schedules you do not want the copy to run.
- Select also cancel pending jobs, then Cancel all, to clear the jobs that queued while the copy was paused.
- Select Resume.
If you use a load balancer#
Load balancer nodes reach the main server's repository through a network share, and each node keeps the UNC path of that share in its own settings. When the repository moves to a new server, point every node at the new share:
- If the old main server is being retired, release its license while it is still running.
- Stop the Reportworq service on every node, and on the old main server.
- Move the repository to the new server as described above. The nodes share one repository, so they also share one license identity: clear it once, not once per node. Share the new Repository folder so that each node's service Log On account can reach it.
- Start the new main server, activate the license, and set its Web App Host. The nodes find the main server through this setting.
- On each node, create a text file called
loadbalancer.txtin the installation directory, next to thesettings.jsonfile. Enter the UNC path of the new server's Repository share as its only line. - Start the Reportworq service on each node. Reportworq reads the file, switches the node to the new repository, and deletes the file. If the file is not deleted, check the Reportworq logs: the most common cause is that the service Log On account cannot reach the UNC path.
- Check that every node appears in the Load Balancer Monitor on the main server.
See Load Balancer for how the nodes are set up.
Feedback on this page
Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.
Email feedback on this pageOr write to support@reportworq.com directly.