Skip to content

Upgrading an Existing Installation

Review the Terminology before proceeding

To upgrade the version of limepkg-engage just tell poetry you want to upgrade

poetry update limepkg-engage

This will update your poetry.lock file to the latest limepkg-engage version that exists within the restrictions set in your pyproject.toml file.

To update to a new limepkg-engage version outside of the restrictions set in your pyproject.toml file, update the limepkg-engage dependency in your pyproject.toml file (Poetry Version Syntax). Then run poetry update limepkg-engage to download the new version of limepkg-engage and update your poetry.lock file.

Upgrading to a New Major Version

Upgrading v1 to v2

Refer to the upgrade information in the Lime Technologies internal documenation

Upgrading v2 to v3

v3 was a cloud specific version of Engage that was quickly replaced by v4. Do NOT migrate to v3 then to v4. Migrate immediately to v4

Upgrading v2/v3 to v4

v4 represents a major rework from Engage in versions v1-v3. That being said the rework was designed to make upgrading easy and maintain backwards compatibility. Automatic migrations will take place to migrate your Activity Triggers to the new version. See the changelog for a list of all changes.

  • Move the Engage API Key from Lime Admin 1 to Application Config (Skip if migrating from v3)

    • Navigate to Lime Admin 1
    • Open Miscellaneous > Lime Engage > Api Configuration
    • Copy the api_key value
    • Follow the Connect CRM to the Engage API instructions and use the API key you just copied
    • Open pyproject.toml
    • Update the limepkg-engage dependency to limepkg-engage = "^4.0.0"
    • Run poetry update limepkg-engage
    • Push your changes to github
    • Cloud: Deploy to cloud
    • On Premise: Install the solution and then restart the app server and event handler services

Thats it! There are no required changes that need to be made to your Activity Trigger configuration in Lime Admin 2, or to your existing competitions.

Verify the upgrade worked

  • Check the event handler and app server logs

    • Look for any Engage ERROR or CRITICAL messages. If the upgrade was able to complete successfully you will not have any ERROR or CRITICAL messages from Engage
    • Engage runs migrations the first time its configuration is fetched. Not all Activity Triggers can be migrated to the new format. When an Activity Trigger cannot be migrated, it is deactivated by setting the active attribute to false on the Activity Trigger.
    • If an Activity Trigger is deactivated, a message will be logged at the ERROR level.
    • Deactivated Activity Triggers can be reactivated by opening the Activity Trigger in Lime Admin 2, toggling show code editor in the upper right corner, and editing the json of the Activity Trigger until it is valid. Then change active from false to true

  • Verify the config shows in Lime Admin 2

    • Open Lime Admin 2
    • Select Addons from the sidebar menu

    • Engage should now appear as an entry under Addons

      • If Engage does not appear under Addons you are not running a v4+ version of limepkg-engage. Make sure you followed all the migration steps.

    • Select Engage from the sidebar menu

    • You should see a list of the Activity Triggers that were previously configured.
    • Select the Activity Triggers and verify they look OK as limepkg-engage v4 will migrate the Activity Triggers to a new format.

  • Test an Activity Trigger

Back to top