This chapter describes how to upgrade Oracle Communications Design Studio and Design Studio projects, and how to upgrade productized cartridges and cartridge packs.
See Design Studio Concepts for more information about working with productized cartridges and other predefined data models. See UIM Cartridge Guide for more information about cartridge packs.
When upgrading Design Studio, ensure that Design Studio component and project backups are up-to-date. Also, determine how to upgrade projects and design environments for all users simultaneously. Finally, communicate changes and steps required by users to ensure a smooth transition.
To upgrade Design Studio:
Plan your upgrade.
See "Planning the Upgrade Process" for more information.
Prepare for the upgrade.
See "Preparing for the Upgrade" for more information.
Perform the upgrade.
See "Performing the Upgrade" for more information.
Perform post-upgrade tasks.
See "Performing Post-Upgrade Tasks" for more information.
When planning your Design Studio upgrade, consider the following:
Which resources need to be backed up?
Before upgrading to a new Design Studio version, back up the current Design Studio environment and project data files so that you can return to the current version, if necessary.
Are all users on the same release version?
All individual Design Studio users should upgrade to the new version from the same existing version. Users working in different versions may have project artifacts that are not compatible with the new version. Users must upgrade to new versions simultaneously, and all projects must be upgraded to the new version. Upgraded projects are not compatible with previous versions of Design Studio.
What will happen if the upgrade fails?
Errors that occur during an upgrade can create an unstable environment. Before beginning the upgrade process ensure that you are able to return the system to the initial state in the event of a failure. If an upgrade fails, collect all pertinent information to send to your support team, and return the system to the initial state prior to attempting the upgrade process again.
See Design Studio System Administrator's Guide for information about backing up and restoring Design Studio.
When preparing for your Design Studio upgrade:
Define project references if you are upgrading to Design Studio (releases 7.2.4 and later) from releases prior to 7.2.0. See "Defining Project References" for more information.
Prepare the source control repository. See "Preparing the Source Control Repository" for more information.
Back up Design Studio projects. See "Backing Up Projects" for more information.
Upgrading to Design Studio from releases prior to 7.2.0 requires that you define project references (within your existing version of Design Studio) prior to the upgrade. Defining project references requires that you specify the dependencies for each project to ensure that all dependent projects are upgraded in the correct order. See the Design Studio Help in your previous version of Design Studio for information about defining project references.
Note:
If you are upgrading Design Studio from release 7.2.0 or from any release subsequent to 7.2.0, existing project references should already be defined correctly. Oracle recommends that you verify that your existing project references are set up correctly prior to your upgrade.Before upgrading, restructure your projects to reduce or eliminate mutual and cyclic dependencies. Mutual or cyclic project dependencies may cause problems during upgrade. You can determine project dependencies by closing a project, performing a clean build, and reviewing the broken reference problem markers that highlight cross-project relationships.
To define project references before upgrading from releases prior to release 7.2.0:
Start your existing version of Design Studio.
From the Studio menu, select Show Design Perspective.
Click the Studio Projects tab.
In the Studio Projects view, select a Design Studio project.
(Optional) If using a source control system, check-out the .project file of the selected project.
Many source control systems use optimistic locking and do not require an explicit file check-out. See the source control system documentation for details specific to your system.
In the Studio Projects view, right-click the selected project and select Properties.
The Properties dialog box appears.
In the left-column menu tree, select Project References.
A list of all projects defined in the workspace appears.
Select all dependent projects that the source project references.
Click OK.
(Optional) If using a source control system, check-in the modified .project file of the selected project.
To prepare the source control repository, ensure that all of your Design Studio users check-in (or discard) any uncommitted project data file changes.
Note:
Oracle recommends that you use a source control system. See Design Studio Developer's Guide for information about incorporating source control into your backup strategy.To identify a clear transition point, tag or branch all Design Studio projects in the source control repository prior to the upgrade. This ensures that you are able to determine the Design Studio application version required to build previous versions of your cartridges and cartridge packs. Additionally, tagging or branching provides a clear restore point if the upgrade fails.
See the source control system documentation for tag and branch details specific to your system.
Back up all projects before upgrading Design Studio. Ensure that you include all Design Studio components and project data files (preferably in source control). Instruct your individual Design Studio users to export the workspace preferences that they want to restore in a new workspace.
See Design Studio System Administrator's Guide for information about backing up Design Studio.
Upgrade Design Studio for all users and build systems simultaneously. Projects opened in a new version will be upgraded for use in the new version and will no longer work predictably in old versions.
To upgrade Design Studio:
Obtain a new Design Studio software package.
Design Studio software packages for new releases are available on the Oracle software delivery website:
Design Studio software packages for patches are available on the My Oracle Support website:
Install the new version to a new location.
Installing to a new location minimizes conflicts that can occur when installing over an existing installation. Make the new installation available to all users and update automated build systems to point to the new location. See "Installing and Configuring Design Studio" for more information.
Create a new distributable archive file for your users.
Upgrade Design Studio projects.
See "Upgrading Projects" for more information.
Instruct users to download the new distributable archive file and extract it to a new location.
Instruct users to create new workspaces with upgraded projects.
Upgrade Design Studio build systems to use the new version.
You must perform a one-time upgrade of your projects. Additionally, you must obtain and import the latest versions of all sealed productized cartridges if you want to use the cartridges in the updated version.
When upgrading projects, you may be required to update cartridge project target versions, depending on the version for which your existing cartridge projects are built and the version of Design Studio to which you are upgrading. The project target version indicates the version of the run-time application instance to which the cartridge project will be deployed. Design Studio builds your project to be compatible with the run-time software version you specify on the Project editor Properties tab. See the Design Studio Help for more information about the Project editor and for more information about the Target Version field. See your application documentation for information about application server version compatibility and for target version instructions specific to each application.
During the upgrade process, Design Studio automatically detects old project versions and completes all necessary project upgrades in the workspace. When the upgrade process completes, Design Studio saves the information about the upgrade process in the project-dir/upgradeLog/upgrade.log file. All information about the upgrade process, including notifications about failed upgrades, is included in this file.
Upgraded projects are not compatible with previous Design Studio versions. Ensure that you upgrade copies of projects or use source control. Project upgrades should be performed once by a single team member. The upgraded project should then be distributed to other users.
Note:
Before you upgrade projects created in versions prior to Design Studio release 7.2.0, you must define all project references in your original version of Design Studio. See "Defining Project References" for more information.To upgrade projects:
Complete all upgrade preparation steps.
See "Preparing for the Upgrade" for more information.
Check-out all project data files from the source control system.
Ensure that the project data files are writable.
Some source control systems use an optimistic locking strategy and require no additional steps for implicit check-outs. Other source control systems may require explicit check-out of each project data file. See the documentation specific to your source control system for more information.
Start Design Studio and create a new workspace.
Because workspaces contain caching and version-specific content, Oracle recommends that you create a new workspace when upgrading.
Determine the order in which you will upgrade the projects.
Start with projects with no dependencies. Upgrade dependent projects first or in conjunction with those projects that define dependencies.
Start the upgrade.
You start the upgrade process any time you open a project that requires an upgrade to the current Design Studio version. For example, you start the upgrade process when you:
Start Design Studio
Switch workspaces
Open a closed project
Import projects with the Design Studio import wizard
If an open project requires an upgrade, the Upgrade Project wizard appears, listing all projects and dependent projects that require an upgrade.
Confirm that the projects are in the correct order.
If the projects are not upgraded in the proper order, the upgrade process can fail and leave the project in an unknown state. Design Studio determines the correct order in which to upgrade the projects based on the dependencies defined for the project (the lowest project in the dependency hierarchy is upgraded first). If you have not properly defined the project dependencies, you must manually set up the proper order.
If the projects are not in the correct order, do one of the following:
Select a project and click Move Up or Move Down to change the order of the projects.
Cancel the upgrade process, return to your previous version of Design Studio, and define the project dependencies.
See "Defining Project References" for information about how to define project references.
(Inventory projects only) Click Next.
When upgrading Design Studio for Inventory and Design Studio for Network Integrity projects, the wizard displays any characteristics that require a name change.
(Inventory projects only) Click Next and then select the Target Version.
Cartridge project target versions specify the version of the run-time application instance to which a cartridge project will be deployed. Design Studio builds your project to be compatible with the run-time software version specified in this field. After you import a project, you can change the Target Version value on the Project editor Properties tab. Design Studio automatically sets the Java execution environment based on the selected target version.
(Design Studio Model projects in releases before Design Studio 7.3.5 only) Validate Design Studio Model project Technical Action entity values.
When you upgrade a Design Studio Model project that contains Technical Action entities, this Studio Project Upgrade wizard requires you to validate the information defaulted for the application role, target, and target type for each technical action; or, if this information is incorrect or absent, to provide it.
For each technical action, do the following:
Validate or select an application role.
An application role represents a type of downstream delivery system that is responsible for a specific type of delivery, such as activation, supply chain management, work force management, and so forth.
Design Studio obtains the application role from the Technical Action entity Notes tab if the value is defined as ApplicationRole=applicationrole. You can select a different application role value, if needed.
Validate or specify a target.
A target is the resource or resource facing service that represents an instance of an entity in the network against which the action executes.
Design Studio obtains the target from the Technical Action entity Notes tab if the value is defined as TargetSpecification=target. You can specify a different target value, if needed.
Validate or select a target type.
For all technical actions, Design Studio defines the target type as Resource. You can change this value to Resource Facing Service, if appropriate.
Click Finish.
The upgrade process completes and the Display Upgrade Log dialog box appears.
Do one of the following:
Click Yes to review the generated upgrade log file.
Click No to complete the upgrade process without reviewing the generated log file. You can view the update logs at a later time.
(Optional) If the upgrade fails, review the upgrade logs to determine the cause of the failure, and then do the following:
Roll back the system to the pre-upgrade state
Resolve the cause for the failure
Retry the upgrade
After a successful upgrade, commit the changes to the source control system.
Note:
If you cancel the project upgrade before the upgrade process completes (by clicking the Upgrade Project wizard Cancel button) the project remains open in the workspace. You must close and reopen the project to attempt the upgrade again before working in the project. Do not perform any work in a project that has failed to successfully complete the upgrade process. See the Design Studio Help for information about opening and closing projects.Note:
When upgrading Design Studio for Inventory cartridge projects that include changes to tool tips or characteristic display names, you must redeploy the UIM application server when you deploy the cartridge that contains the changes.After the upgrade, do the following:
Review and archive upgrade logs.
Perform a clean build of each project.
Initiate command-line builds on automated build systems.
Distribute the new Design Studio version.
Instruct all individual Design Studio users to import the upgraded projects into a clean workspace.
Remove old Design Studio application installations.
This section describes how to upgrade a productized cartridge or a cartridge pack to a new version.
Before upgrading to a new version of a productized cartridge or cartridge pack, ensure that the uncommitted changes for all Design Studio projects in the source control system are checked-in or discarded.
If your are upgrading more than one cartridge or cartridge pack, perform the upgrades individually. Start with projects with no dependencies. Upgrade dependent projects first or in conjunction with those projects that define dependencies. Ensure that the workspace includes all related projects during the upgrade.
Additionally, ensure that you tag or branch all Design Studio projects in the source control repository prior to the upgrade to identify a clear transition point. Tagging or branching provides a clear restoration point in the event of a failed upgrade.
Finally, ensure that a current backup is available for all Design Studio projects. See Design Studio System Administrator's Guide for more information.
To upgrade a productized cartridge or cartridge pack:
Back up the cartridge project or cartridge pack project that you intend to upgrade.
Start Design Studio.
From the Studio menu, select Show Design Perspective.
From the Project menu, deselect Build Automatically.
Temporarily disabling the automatic build prevents unnecessary builds and problem markers during the upgrade procedure.
Click the Studio Projects tab.
In the Studio Projects view, right-click the project to be upgraded and select Delete.
The Confirm Project Delete dialog box appears.
Select the Also delete contents under option.
Selecting this option removes the current version of the project from your local file system.
Click Yes.
The project content is deleted from the workspace and the local file system.
Right-click in the Studio Projects view and select Import, and then select Import Project.
The Import Projects dialog box appears.
Do one of the following:
If your project is contained in an archive file (for example, in a TAR file or ZIP file), select Select archive file.
Otherwise, select Select root directory.
Click Browse.
Locate the directory containing the new version of the project and select it.
Click OK.
In the Projects area, select the project to import.
Ensure that the Copy projects into workspace check box is selected.
Click Finish.
The project is added to your workspace.
From the Project menu, select Clean.
The Clean wizard appears.
Select Clean all projects and then select Start a build immediately.
Click OK.
A dialog box appears, showing the progress of the build activity. The projects in the workspace are cleaned and a full build is performed on all projects. The build completion time depends on the size of workspace.
From the Project menu, select Build Automatically.
Resolve warning and error markers.
New warnings and errors may appear following a project upgrade. Markers may be caused by changes to the data model, such as type changes, name changes, or deprecation or removal of content. Use the Refactoring menu actions (such as Resolve and Replace With) to facilitate problem marker resolution. See the Design Studio Help for more information about refactoring data element names and locations.
(Optional) If using a source control system, synchronize the new versions.
See "Synchronizing Project Versions" for more information.
If you are using a source control system to manage revisions of productized cartridges and cartridge packs, you can synchronize the new version.
To synchronize new project versions:
In Design Studio, right-click in the Studio Projects view and select Team, then select Share Project.
Follow the steps in the wizard to share the project to the same repository location as the previous project version.
Resolve conflicts following synchronization using local file and directory versions.
Commit content to the repository.
See your source control system documentation for information about sharing projects and resolving synchronization conflicts.
Note:
If you encounter a blocking issue, do not check-in the changes. If necessary, you can cancel the upgrade by rolling back to the latest version under source control.Cartridge projects designed for a specific server release must match the preferred execution environment of the application server. To retarget existing cartridge projects for deployment to the current release application server, you must manually update the cartridge target version to the current release number and update the cartridge execution environment to the current supported Java version.
To upgrade existing cartridge projects to the current release:
Install Java and add entries for each installed JRE used in development.
To install Java and add Java entries:
Install Java.
See "Copying Java Runtime Environment into Oracle Enterprise Pack for Eclipse" for more information.
In Design Studio, from the Window menu, select Preferences.
The Preferences page appears.
Select Java, and then select Installed JREs.
Add an entry for each JRE that you intend to use during cartridge project development.
Update the cartridge project target version.
To update the cartridge project target version:
From the Studio Projects view, double-click a Project entity to open the entity in the Project editor.
In the Target Version field, select the current version.
Update the cartridge project execution environment.
To update the cartridge project execution environment:
From the Studio Projects view, right-click a Project entity and select Properties.
The Properties dialog box appears.
Select Java Build Path, and then click the Libraries tab.
Select JRE System Library and then click Edit.
The Editor Library dialog box appears.
Select the Execution environment option, and then select the current Java version from the list.
Click Finish and then click OK.
Perform a clean build.
See Design Studio Help for information about performing clean builds.