Overview

Our application is built entirely on the Salesforce platform, which means all development and release cycles are closely aligned with Salesforce’s own releases.
To ensure full compatibility and platform stability, we publish our product releases one month after each Salesforce release (March, July and November)
All smaller improvements and bug fixes are delivered through patches or hot fixes if related to the gateway application
To maintain system stability and ensure the best possible experience, we strongly recommend all customers stay on the latest patched version of their current major release.

Major Releases

Purpose: Introduce significant new functionality, adapt to Salesforce platform updates, or implement structural product changes.

Typical content includes:

• New features or modules

• New objects, fields, or relationships

• Updated or extended business logic

• Major architectural changes or Salesforce alignment adjustments

Example:
A release introducing a new Delta Invoicing, Campaign Builder, connections, new custom objects, and updated automation logic.

1. Manual Adjustments

1.1 Before the Update to the major release

• Use a sandbox to test a new version before installing it in production

  • and define recurring test cases for core business processes.

  • Refresh your sandbox before installing a release

  • and think about relevant test data.

• Deactivate Dashboards if you have too many in the system

• Use the Translation Workbench *

• We are recommending the use of the Translation Workbench and overwrite/translate picklist values and record types. This will not be changed by the package upgrade. Additionally, you can safely add your own values. The exception to this is global label values (see below).

1.2 After the Update to the major release

• Always check the latest version Change Log to make sure your picklists and record types are up to date and work with the new features. Also, make sure to not use deprecated objects or fields anymore.

• Check the Global Value Sets (Global Picklists) for Spring 2018 and up. Salesforce changed the behaviour of global value sets in all managed package upgrades to match the behaviour of standard value sets. Therefore you will now have to manually update any of ADvendio's global picklists with 

  • Label and API names for non-packaged individual values don’t change.

  • Global label values change back to the standard package values with each upgrade!

• Enable new features (see below)

• Reschedule Apex Jobs for ADvendio classes after an update to ensure the correct function.

2. How to handle Upgrade Error Messages

2.1 Apex jobs errors

Updating to the latest ADvendio major release might have caused a runtime error in your apex jobs.

If you are getting error messages similar to 'Ad-Server Delivery Report Lifetime': Attempt to de-reference a null object Please reschedule the following APEX jobs:

1. Delivery report. Here is how: https://advendio.atlassian.net/wiki/spaces/SO/pages/1521614895

2. Account Turnover (class: AccountTurnover). You will have to reschedule with the standard Salesforce function "Schedule Apex". Here is how to: https://advendio.atlassian.net/wiki/spaces/SO/pages/61800478

3. Campaign Item Revenue Split (class: CampaignItemRevenueSplit). You will have to reschedule with the standard Salesforce function "Schedule Apex". Here is how to: https://advendio.atlassian.net/wiki/spaces/SO/pages/80674853

2.4 Path Record Type errors

2.4.1 Media Campaign Path

You manually created a sales path for the Media Campaign object, we added the path with version 2.85, if you're installing from a lower version and encounter this error you need to delete your path, install (a version that has the path disabled 2.102 and up) and afterwards create your own path using record types.

2.4.2 Advertising Material Path

Options:

• Use ADvendio picklist values and change the labels or use the translation workbench

• Alternatively, create your own record type and add your values to this new record type.

otherwise, you can not upgrade to a newer version.

2.5 Active Lookup Limit

The Limit of active lookups for an object is reached (in one version we added 3 active lookups, which we later removed because of that error) This error will happen if you already have 5 active and required lookups for an object and then the package tries to add a new one. This can be solved by setting your lookups to optional.

2.6 Custom Field Naming Error 

This error occurs when you have created a custom field and ADvendio tries to add a new field/object with the same API name.

Other Know issues can be found here: https://advendio.atlassian.net/wiki/spaces/SO/pages/1007157284

3. General Recommendations

To upgrade safely, please adhere to the following recommendations:

3.1 Dos

• Keep as close as possible to the standard.

• Think about changing internal processes first before changing the system.

• Before developing custom functionalities on your own, ask your ADvendio consultant if there is already something similar on the roadmap or if ultimately an existing feature could be enhanced.

• Read the release notes carefully.

  • In case of any questions, please don´t hesitate to contact us.

  • Pay special attention to all custom developments that might be interacting with ADvendio

• Use a sandbox to test a new version before installing it in production

• Determine your own release cycle and reserve resources (especially human resources) to implement your own development and Advendio releases.

• Use as many as possible of the embedded standard workflows and processes.

• Use the provided JavaScript API to embed your own business logic into the campaign builder and commercial optimizer.

• Reschedule Apex Jobs for ADvendio classes after an update to ensure the correct function.

3.2 Don'ts

• Don’t install a release without testing it in a sandbox!

• Don’t integrate Custom JavaScript in the Media Configuration which works contrary to logic, workflows or processes in the standard of the ADvendio package.

• Don’t re-develop a function on your own that is already part of the ADvendio Package.

• Don’t use the same API names for objects or fields in ADvendio objects that are already defined in the package. An object or field in an ADvendio object even without prefix (in its API name) will be considered part of a component of ADvendio which leads to incorrect behaviour in ADvendio.

• Avoid using validations for "irrelevant" data changes in order to prevent errors in automated processes (e.g. when validating an account phone number, check if the number has been changed - don’t start this validation if other fields have been updated only.)

4. How to adapt or enable new ADvendio features

Some of the new features can't be packaged in Salesforce and therefore need manual work in order to work correctly. Especially if you are upgrading and not installing the first version, some values have to be manually set.

The first step is to read the newest Change Logs.  Change logs can be found next to the release notes in the corresponding seasonal release folder. The Change Log lists all values and fields that you need to consider if you like to introduce a new feature. 

So please consider the following if the new feature is used:

1. Record types you might have to

   1. add them manually using the correct spelling from the change log and

   2. translate or overwrite the value into the local language

   3. Adjust the access rights for the corresponding user profiles. 

2. For additional picklist values, make sure to

   1. add them manually using the correct spelling from the change log and

   2. translate or overwrite the value into the local language

   3. add them to the correct record type(s)

   4. and adjust the access rights to the profiles that are needed.

3. New fields or deprecated fields in Layouts

   1. Adjust your layouts appropriately to add new fields and their visibility. 

Patches

Purpose: Deliver targeted updates or fixes between major versions.
Patches may include bug fixes, gateway or connection updates, or minor product improvements.

Patch types include:

• Bug Fixes: Resolve issues identified after a major release.
  Gateway / API Updates: Apply necessary adjustments to third-party integrations (e.g., Google, Meta, or other connected systems).
  Improvements: Implement small logical or usability enhancements that don’t require a full major release.

Important:
If a patch updates an integration (for example, Google API) for version 2.177.15, only customers on version 2.177.15 will receive the update. So it is critically important for ADvendio that the customers use the latest patched versions.

ADvendio encourages customers to always install the latest patched versions. Each bug fix is included in its corresponding patch, so if a customer chooses to install an older patch, they risk experiencing issues that have already been addressed in more recent updates.

Customers on earlier versions will not have access to the fixed or updated integration until they upgrade.

Gateway and Connection Changes

Our product includes multiple gateway and connection components (e.g., Google Ads, Meta, or other external APIs) that may evolve independently of the Salesforce-based product version.

Each major Salesforce version (e.g., SF 2.177) may also have a corresponding gateway version (e.g., gw. 2.177).
This gateway version reflects the state of all integration capabilities — for example, authentication methods, API endpoints, and data exchange logic.

Key points:

• The ADvendio version (e.g., SF 2.177.15) represents the core product release built on the Salesforce platform.

• The gateway version (e.g., SF 2.177.15, gw 2.177.8) indicates the specific integration layer version used within that product version.

• When we patch Salesforce-based capabilities (e.g., logic, objects, or metadata), the gateway version might not change.

• When we patch only the gateway or connection logic (e.g., update to Google or Meta API), we increment the gateway version number in the Salesforce patch, so for example, if the customer installs the Advendio 2.177.15 patch version, automatically, 2.177.8 GW will be there

• Gateway changes are typically included in patches for the current major version.

• If a gateway update requires significant redevelopment (for example, a full API migration), it will be included in a major release.

• In rare and exceptional cases, when a connection becomes completely non-functional, we may issue a hotfix — but this is not part of the standard process and is only done to restore essential functionality.

Release Rhythm