Performing a build upgrade performing-a-build-upgrade
This section will provide you with an in-depth walkthrough on the upgrade process and the steps to identify and resolve conflicts.
The build upgrade must be carried out with caution, its impacts must be fully considered beforehand and the procedure must be completed with a high level of discipline. To ensure a successful upgrade, ensure that only expert users perform the steps outlined below. In addition, we strongly recommend getting in touch with Adobe Customer Care before starting any upgrade.
The following prerequisites are needed:
- Understanding of the Campaign Architecture
- Systems and server side knowledge
- Administrative rights and permissions
You can find more information in these sections: Updating Adobe Campaign, Migrating to a new version.
For hosted and hybrid instances, you must request the build upgrade to Adobe Technical Operations team. For more on this, refer to the Frequently Asked Questions section at the bottom if this page. Also consult the build upgrade FAQ.
Prepare the upgrade
Before starting the build upgrade, you must perform a full preparation as described below.
Once the system is ready to be upgraded, a build upgrade takes at least 2 hours.
The build upgrade process requires the following resources:
- an Adobe architect - to understand the database structures (out-of-the-box schemas and any additional schemas that have been added, campaign designs, and any critical path functionality that must be started and tested in a specific order).
- a project manager - In the case where the build upgrade involves many different instances (production, staging, testing) and other third party servers and applications (databases, SFTP sites, messaging service providers), having a project manager to coordinate all of the testing is considered a best practice.
- an Adobe Campaign administrator - your administrator knows the server’s configuration including but not limited to: security, folder layout, reporting, and import\export requirements. Please do not perform a build upgrade without your administrator.
- an Adobe Campaign operator (marketing user) - a successful upgrade relies upon the user’s ability to perform their daily tasks successfully. For this reason, always include at least one of your daily operators in your testing of the upgraded servers.
Planning
Here are the key points on how to plan a build upgrade:
- Reserve at least 2 hours for the upgrade.
- Distribute contact details for Adobe and customer staff.
- For hosted instances: Adobe and customer staff will coordinate the time for the upgrade and who will execute.
- For on-premise instances: customer staff manages the entire process - if assistance in testing of customized workflows and delivery logic is needed, consulting services should be brought in.
- Determine and confirm which version of Adobe Campaign you want to upgrade to - consult the Adobe Campaign Classic release notes.
- Confirm possession of upgrade executables.
Key people
The build upgrade process requires the following people to be involved:
-
Adobe architect: for hosted or hybrid architectures, the architect must coordinate with Adobe Campaign Client Care.
-
Project manager:
-
for On Premise installations: the customer’s internal Project Leader leads the upgrade and manages lifecycle tests.
-
for Hosted installation: the hosting team will partner with the Adobe Campaign Client Care team and the customer to coordinate the upgrade timeline for all instances.
-
-
Adobe Campaign Administrator:
-
for On Premise installations: the administrator performs the upgrade.
-
for Hosted installations: the hosting team performs the upgrade.
-
-
Adobe Campaign operator\marketing user: the operator runs tests on development, test and production instances.
Prepare the build upgrade
Before starting the build upgrade, on-premise customers need to perform the following preparation:
-
Ensure any development work can be exported before the upgrade, export as packages.
-
Perform a full backup of the databases for all instances of the source and target environments.
-
Get the latest version of your server configuration file.
You also need to know all the useful command lines before starting a build upgrade:
- nlserver pdump: lists running processes
- nlserver pdump -who: lists active client sessions
- nlserver monitor -missing: lists missing properties
- nlserver start process@instance-name: starts a process
- nlserver stop process@instance-name: stops a process
- nlserver restart process@instance-name: restarts a process
- nlserver shutdown: stops all Campaign processes
- nlserver watchdog -svc: starts the watchdog (UNIX only)
Perform the upgrade
Procedures below are only performed by on-premise customers. For hosted customers, it is taken care by the hosting team. To update Adobe Campaign to a new build, the detailed procedure is described below.
Duplicate the environment
Here is how you duplicate an Adobe Campaign environment, in order to restore a source environment to a target environment, resulting in two identical work environments.
To do this, follow the steps below:
-
Create a copy of the databases on all instances in the source environment.
-
Restore these copies on all instances of the target environment.
-
Run the nms:freezeInstance.js cauterization script on the target environment before starting it up. This will stop all processes interacting with the outside: logs, tracking, deliveries, campaign workflows, etc.
code language-none nlserverjavacsriptnms:freezeInstance.js–instance:<dev> -arg:run -
Check cauterization, as follows:
-
Check that the only delivery part is the one which ID is set to 0:
code language-none SELECT * FROM neolane.nmsdeliverypart; -
Check that the delivery status update is correct:
code language-none SELECT iSate, count(*) FROM neolane.nmsdeliveryGroup By iProd; -
Check that the workflow status update is correct:
code language-none SELECT iState, count (*) FROM neolane.xtkworkflowGROUP BY iState; SELECT iStatus, count (*) FROM neolane.xtkworkflowGROUP BY iStatus;
-
Shut down services
In order to replace all files with the new version, it is required that all instances of the nlserverservice are shut down.
-
Shut down the following services:
- Web services (IIS): iisreset /stop
- Adobe Campaign service: net stop nlserver6
note note NOTE Make sure that the redirection server (webmdl) is stopped, so that the nlsrvmod.dll file used by IIS can be replaced with the new version. -
Validate that no tasks are active by running the nlserver pdump command. If there are no tasks, then the output should resemble the following:
code language-none C:\<installation path>\bin>nlserverpdump HH:MM:SS > Application Server for Adobe Campaign version x.x (build xxx) dated xx/xx/xxxx No tasks -
Check the Windows Task Manager to confirm that all processes have stopped.
Upgrade the Adobe Campaign Server Application
-
Run the Setup.exe file. If you need to download this file, access the Download center.
-
Select the installation mode: Update or Repair.
-
Click Next.
-
Click Finish: the installation program copies the new files.
-
Once the operation is complete, click Finish.
Synchronize resources
-
Open up the command line.
-
Run nlserver config -postupgrade -allinstances to perform the following:
- Synchronize resources
- Update schemas
- Update the database
note note NOTE This operation should only be performed once and only on an nlserverweb application server. To synchronize only one database, run the following command:
code language-none nlserver config -postupgrade -instance: <instance_name> -
Check if the synchronization has generated any errors or warnings.
Restart services
The following services need to be restarted:
- Web services (IIS): issreset /start
- Adobe Campaign service: net start nlserver6
Client consoles update
The client console must be on the same build as the server instance.
On the machine where the Adobe Campaign application server is installed (nlserverweb), download and copy the file:
Setup-client-7.xxxx.exe in [path of the application]\datakit\nl\en\jsp
The next time client consoles are connected, a window will inform users about the availability of a new update and offer them the possibility of downloading and installing it.
Specific additional tasks
Some configurations require specific additional tasks to update to a new build.
Transactional messaging
When Transactional Messaging (Message Center) is enabled on your Campaign instance, you need to perform these additional steps to upgrade:
-
Update the Message Center production server to the chosen version.
-
Run the postupgrade scripts.
-
Run tests and ensure that the emails are successfully received through the Message Center production instance.
-
Upgrade clients and clear cache.
-
Export packages:
- Export packages using the client package export tool
- Import schema package
- Disconnect and reconnect client
- Update database
- Disconnect and reconnect
- Import Admin package
- Import Content package
- Import Content Management package
- Disconnect and reconnect
- Perform a quick sanity check of workflows
-
Publish Message Center templates to ensure that the interface between servers and Message Center instance is working.
-
Run tests to ensure that emails are successfully received through the Message Center production instance.
-
Run workflow tests in production to ensure that deliveries are received.
Mid-sourcing
In the context of a mid-sourcing environment, you need to perform these additional steps to upgrade:
-
Contact Adobe Customer Care to coordinate the upgrade of the Mid-Sourcing server.
-
Validate that the version has been updated by running a test link. For example:
code language-none http://[InsertServerURL]/r/test
In case of conflicts
Identify conflicts
You need to check the synchronization result. This procedure is only performed by on-premise customers. For hosted customers, it is taken care by the hosting team. There are two ways to view the synchronization result:
In the command-line interface, errors are materialized by a triple chevron ‘>>>’ and synchronization is stopped automatically. Warnings are materialized by a double chevron ‘>>’ and must be resolved once synchronization is complete. At the end of the postupgrade, a summary is displayed in the command prompt. It can look like this:
YYYY-MM-DD HH:MM:SS.749Z 00002E7A 1 info log =========Summary of the update==========
YYYY-MM-DD HH:MM:SS.749Z 00002E7A 1 info log <instance name> instance, 6 warning(s) and 0 error(s) during the update.
YYYY-MM-DD HH:MM:SS.749Z 00002E7A 1 warning log The document with identifier 'mobileAppDeliveryFeedback' and type 'xtk:report' is in conflict with the new version.
YYYY-MM-DD HH:MM:SS.749Z 00002E7A 1 warning log The document with identifier 'opensByUserAgent' and type 'xtk:report' is in conflict with the new version.
YYYY-MM-DD HH:MM:SS.750Z 00002E7A 1 warning log The document with identifier 'deliveryValidation' and type 'nms:webApp' is in conflict with the new version.
YYYY-MM-DD HH:MM:SS.750Z 00002E7A 1 warning log Document of identifier 'nms:includeView‘ and type 'xtk:srcSchema' updated in the database and found in the file system. You will have to merge the two versions manually.
If the warning concerns a conflict of resources, user attention is required to resolve it.
The postupgrade_ServerVersionNumber_TimeOfPostupgrade.log file contains the synchronization result. It is available by default in the following directory: installationDirectory/var/<instance-name>/postupgrade. Errors and warnings are indicated by the error and warning attributes.
Analyze conflicts
How is a conflict found?
Conflicts can be found within the postupgrade.log on the server in question or within the Campaign client interface (Administration > Configuration > Package management > Edit conflicts).
The document with identifier ‘stockOverview’ and type ‘nms:webApp’ is in conflict with the new version.
If a conflict is found, check if the following conditions match:
- Has the object been modified or customized by the customer?
- Has the object changed in the product?
If neither of these conditions apply, this is a false positive. If both these conditions apply, a real conflict has been found.
Has the object been modified by the customer?
- Identify the conflicting object.
- Ask the customer if they modified the object.
- Is there anything unusual with the object?
- Is the last modified date set in the object’s code?
- Examine the XML code from the conflict for “_conflict” attributes. Does it look like a customization?
Has the object been changed in the new build?
- Any “usual suspects?” Built-in web applications or reports (ex: ‘deliveryValidation’, ‘deliveryOverview’, ‘budget’).
- Examine the change logs for any updates.
- Ask Adobe Campaign experts.
- Perform a “diff” on the code.
Resolve a conflict
To resolve conflicts, apply the following process:
-
In the Adobe Campaign explorer, go to Administration > Configuration > Package management > Edit conflicts.
-
Select the conflict you want to resolve in the list.
There are three options to resolve conflicts: Accept the new version, Keep the current version, Merge the code (and declare as resolved), Ignore the conflict (not recommended).
When can I accept the new version?
- If you want the standard features.
- If you don’t have customizations (all customizations will be removed)
When can I keep the current version?
- If you have customizations
- If you don’t want to merge
- If you don’t need any fixes on the conflicting object from the upgrade
When to perform a merge?
- Only forms, reports and web applications can be merged.
- Some minor merges can be resolved without understanding the code.
- More complex merges should be performed by someone with the appropriate skills and ability.
- See Perform a merge.
What if I ignore the conflicts?
- The conflict will remain
- The object will not be upgraded
- Long term impacts: version incompatibilities, the customer will not benefit from bug fixes.
Perform a merge perform-a-merge
There are different types of merges:
- Easy merge: custom and new elements are small and unrelated, and there is no coding required.
- No changes: accept new version, only last update date changed, only comments, tabs, spaces or new lines. Example: accidental save.
- Trivial changes: only one line changed. Example: xpathToLoad
- Complex merge: when coding is required. Development skills are required. See Complex merges.
How to merge?
- Get all three versions: the original version, the new version and the custom version.
- Run a “diff” between the original and new versions.
- Isolate the changes.
- If no changes, resolve by keeping current version.
Where to find the code?
- Built-in code is stored in XML files in the datakit folder. Find the XML file that matches the conflicting object. Example: installationDirectory\datakit\nms\fra\form\recipient.xml
- Retrieve the original version: via the Download center or another non-upgraded installation of the product.
- Retrieve the new version: via the Download center or the customer’s installed files.
- Retrieve the custom version: retrieve the object’s source code from within the Campaign client.
How to make a diff?
- Install a text or merge editor, for example Notepad ++, AraxisMerge, WinMerge.
- Open the original file and the new file in the editor.
- Run the diff (compare the two files).
- Identify any differences.
How to merge?
- Start from the custom version.
- Apply the changes.
- Resolve the conflict by declaring it as resolved.
- Check for non-regressions.
If you choose to resolve the conflict manually, proceed as follows:
- In the lower section of the window, search for the conflict_string to locate the entities with conflicts. The entity installed with the new version contains the new argument, the entity that matches the previous version contains the custom argument.
- Delete the version you don’t want to keep. Delete the conflict_argument string of the entity you are keeping.
- Go to the conflict you have resolved. Click the Actions icon and select Declare as resolved.
- Save your changes: the conflict is now resolved.
Complex merges complex-merges
- Understand what the change does: reverse-engineer the changes, examine the change logs, follow up with Adobe Campaign experts.
- Decide what to do with the change.
- Understand what the customizations do: reverse-engineer the changes
Here are the steps to perform a complex merge:
- Copy bits of code from the change set
- Paste to the customized version
- Test for non-regressions of customization
- Test for function of changes
- Perform User Acceptance Testing
- Perform in test environment
Related topics