Cayosoft Administrator upgrade guide

Overview

Upgrading Cayosoft Administrator requires following a few essential steps to ensure a smooth and safe process. This guide covers prerequisites, considerations, and instructions for different upgrade scenarios.

 

Prerequisites

Full server backup

Cayosoft recommends creating a full backup or snapshot of the server where Cayosoft Administrator is installed. 
If you are using VMware or HyperV to host Cayosoft Administrator, review the following articles for instructions on how to backup your virtual servers:

• Virtual Machine Snapshots in VSphere (VMWare)
• Back up Hyper-V virtual machines

 

Manual backup

If you cannot take a full server backup, take a backup of the product databases.

Note: Store the backup archive in a secure location, such as an off-site storage or a secure cloud service.

1. Ensure other users are not connected to Configuration & Automation or Administrative Web Portal.
2. Look at the status light in the console toolbar. Ensure the light is blue, which indicates no tasks are currently running.
3. Navigate to the installation directory (by default it is C:\Program Files\Cayo Software\AdminAssistant).
4. Compress the .db files into a ZIP archive for backup.

Learn more in: Backing up and handling Cayosoft Administrator databases.

Important! If for some reason no backup was created before running the upgrade, or the backup is corrupted, you would still be able to rollback using an automated backup of the configuration database, but the rollback process will be different.

 

Considerations

1. Replication Groups: If using replication groups, upgrade the Publisher instance before Subscribers. Learn more in: Upgrading when replication group is configured. 
2. Remote Console Users: Upgrade the Cayosoft Remote Console after the Publisher and Subscribers. Learn more in: Welcome page. 
3. General Upgrade Notes: A Consent is not granted message may be prompted after the upgrade. This behavior is expected; the Microsoft 365-related permissions are essential for the Cayosoft Administrator operability and must be granted based on the used features. Refer to the following section for additional information: Consent is not granted.

 

Keeping custom rule changes

To retain custom changes:

1. Enable Design Mode for the rule.
2. Select Keep manual changes on upgrade. 
   Note: The Keep manual changes on upgrade option should only be used when explicitly instructed by Cayosoft Technical Support. Using this setting incorrectly may result in unexpected behavior during future upgrades. Always consult with support before enabling this option.
3. Save changes.

 

Upgrade Scenarios

1. From Cayosoft Administrator 11.1 and above - upgrade to the latest version directly within the product. Learn more in: Upgrading from Product UI.
2. From Cayosoft Administrator version below 11 - download the installer manually from the Cayosoft website. Learn more in: Performing a Version Upgrade (Full Backup + Config Backup).

 

Upgrading from Product UI

When a new version is released, a banner will prompt you to upgrade. Choose from the following options:

• Update Now: Initiates the upgrade immediately.
• Schedule Update: Allows you to select a specific time for the upgrade.

Note: To skip the upgrade, go to Configuration > Settings > Version Information in the Administrator console and select Skip This Update. After that, the Check for Updates action won't find any updates until the next version is available for update.

If you need to upgrade to the skipped version, perform a manual upgrade using an installation file. Refer to the Upgrading from installation file section to proceed.

 

Upgrade Procedure

The upgrade process may take up to 30 minutes. The Cayosoft Administrator application will automatically close and perform the update in the background.

Once the update is complete, relaunch Cayosoft Administrator to resume operations.

 

Upgrading from installation file

1. Log in to Cayosoft.com with your cayosoft.com account and download the latest Cayosoft Administrator version.

2. Close the Cayosoft Administrator console and Web Portal on the upgraded server.

3. Double-click the downloaded installer, select Install, and follow the prompts to complete the installation.

4. Start the Cayosoft Administrator console. The initialization may take extra time after the upgrade.

 

Upgrading when replication group is configured

In environments with replication configured, upgrade the Publisher server first. Upgrade every Subscriber server after that. Depending on the network availability in your environment, select one of the following options to update your instances.

 

Cloud upgrade in replication group

In environments with internet access, upgrade your Cayosoft Administrator instances from the cloud. Refer to the following article to learn more about the process: Update product or extension pack from the cloud.

 

Offline upgrade in replication group

In environments with limited or no internet access, upgrade your instances manually. Refer to the steps of the Performing a version upgrade (full backup + config backup) section.

 

Rolling back after unsuccessful upgrade

Rolling back to a full backup

1. Locate the full backup or snapshot created before the upgrade. Ensure it includes both system and application files. Learn more in: Full Server Backup.
2. Follow your virtualization platform's instructions to restore the server:
   • For VMware: Use the vSphere Web Client or other VMware tools to revert to the snapshot.
   • For Hyper-V: Use the Hyper-V Manager or Data Protection Manager to restore the backup.
3. Verify Restoration
   • Ensure the Cayosoft Administrator service is running.
   • Confirm that all settings, rules, and configurations are intact.
4. If changes were made after the backup, consider reapplying them cautiously. Review logs and documentation for any actions performed post-backup.

 

Rolling back using automatic configuration backup

If you haven't created the full server backup or a manual backup, you can still revert to the previous version of Cayosoft Administrator using the steps below:

1. Open the Control Panel, locate the current version of Cayosoft Administrator, and uninstall it.
2. Restore the database:
   1. Navigate to the backup directory C:\ProgramData\Cayo Software\AdminAssistant\Backups.
   2. Identify the most recent backup file created before the upgrade.
   3. Follow the steps to reinstate the previous configuration.
3. Reinstall the previous version.
   • Check the Updates folder at C:\ProgramData\Cayo Software\AdminAssistant\Updates for the installer used during the upgrade.
   • If unavailable, locate the installer from your last upgrade or contact Cayosoft Support. Provide the exact version and build to get the correct installer.

 

Rolling back using manual configuration backup

If you need to roll back to a previous version of Cayosoft Administrator using a manual backup, the steps are the same as for an automatic configuration backup, except you will copy your manually backed-up files instead of files from the Backups folder.

1. Open the Control Panel, locate the current version of Cayosoft Administrator, and uninstall it.
2. Restore the database:
   1. Navigate to the location where you saved your manual backup files.
   2. Identify the most recent backup file created before the upgrade.
   3. Follow the steps to reinstate the previous configuration.
3. Reinstall the previous version.
   • Check the Updates folder at C:\ProgramData\Cayo Software\AdminAssistant\Updates for the installer used during the upgrade.
   • If unavailable, locate the installer from your last upgrade or contact Cayosoft Support. Provide the exact version and build to get the correct installer.

 

Post-upgrade Steps

• Cloud Upgrade: No additional actions are required. If follow-up steps are needed, a banner will appear on the home page.
• Action Required: If any issues occurred during the upgrade, the home Cayosoft Administrator console page will feature the Action Required banner with items to be reviewed.

IMPORTANT: The unresolved action items from before the upgrade may also trigger the Action Required banner. If any, do not treat them as the upgrade follow-up actions.

Canceling a scheduled update

You might need to reschedule or cancel a scheduled update due to unforeseen events. To cancel a scheduled update, click Cancel scheduled update in the right pane of the Version Information menu of the Cayosoft Administrator console.

 

Additional Topics

Consent is not granted

Cayosoft Administrator requires a dedicated Entra ID application to work with your Microsoft 365 data using the Microsoft Graph API. When you first set up the Microsoft 365 extension, Cayosoft Administrator registers the application in your tenant. The app is used to access, read, and write data. Refer to the following article to learn more about the required permissions: Entra ID application permissions required by Cayosoft Administrator Service.

When you update your Cayosoft Administrator instance, the Entra ID application remains the same. If there are any changes to the Microsoft 365 extension functionality (e.g., a new feature has been added to Cayosoft Administrator), the corresponding permissions must be granted to ensure proper operation. This leads to the Consent is not granted message in the main Cayosoft Administrator Console page. To resolve the error, click Grant Consent.

 

Upgrading web portal branding (Banner)

If the native banner changes in the new version, your custom banner will be replaced. Refer to the Branding article for instructions on reapplying it.

 

Upgrading rules

Depending on the upgrade type, updated rules may need to be upgraded. Refer to the following scenarios to learn more about the rule upgrade workflow:

• When you perform a cloud upgrade (i.e., via the Cayosoft Administrator console), the Product Update | Run post-update steps rule runs automatically. No manual rule upgrade is required if the Update all rules setting is set to Yes.
• When you perform a manual upgrade (i.e., using an installation file), review the Rules to be upgraded page and click Upgrade Rule for each or Upgrade All Rules for the bulk upgrade.