Cayosoft Administrator upgrade guide

Overview

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

Prerequisites

Full Server Backup

Cayosoft recommends creating a full server backup or snapshot 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 are unable to perform a full server backup, back up 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 the Cayosoft Administrator console or  Web Portal.

2. Verify the status light in the console toolbar is blue, which indicates that no tasks are currently running.

3. Navigate to the installation directory (C:\Program Files\Cayo Software\AdminAssistant by default).

4. Compress the .db files into a ZIP archive for backup.

Refer to the following article for additional information: Backing up and handling Cayosoft Administrator databases .

IMPORTANT: If no backup was created before the upgrade, or the backup is corrupted, you can still rollback using an automated backup of the configuration database. The rollback procedure will be different.

Considerations

• Delegation roles in v12.4 and later: The deprecated built-in Installed by role in Cayosoft Administrator v12.4 and later versions may affect the Subscriber users in replicated environments. Learn more about the recommended steps for replicated environments in the following section: Installed by role in replicated environments.

• Replication groups: If using replication groups, upgrade the Publisher instance before Subscribers. Learn more in: Upgrading when replication group is configured.

• Remote console users: Upgrade the Cayosoft Remote Console after the Publisher and Subscriber. Learn more in: Welcome page.

• 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 the Technical Support team 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. For Cayosoft Administrator 11 and below: download the installer manually from the Cayosoft website. Learn more in: Upgrading from installation file.

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 Cayosoft Administratorconsole 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. Cayosoft Administrator 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 Cayosoft Administrator 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 Cayosoft Administrator instances manually. Refer to the steps of the Cayosoft Administrator upgrade guide 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: Prerequisites.

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 following 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 Modify Cayosoft Administrator Web Portal Home Page (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.

Installed by role in replicated environments

The dedicated Installed by role in Global Administrators has been deprecated in Cayosoft Administrator v12.4. The Installed by user delegation rule has been added to the Global Administrators role to replace the deprecated role. After the upgrade to v12.4, the delegation rule will be added to the Global Administrators role; the user performing the installation or upgrade will be automatically delegated the role.

In replicated environments, the roles are replicated from the Publisher server to Subscriber servers in your environment overwriting them. To prevent a lockout and have the role correctly replicated, you must manually delegate the correct role to the intended users on your Subscriber server.