Contents

Helpful Links

Serena Documentation Center

SBM 11.0.1 Readme

System Administrator Deprecation List

Terminology Changes

The following terminology and component name changes have been made since the release of SBM 2009 R4.

Supported Configurations

Detailed information about supported platforms and software configuration is available in the Supported Platform Matrix. (Click View to see the complete platform matrix for this release).

Build Numbers

The following component build numbers apply to this version:

• SBM User Workspace and Serena Work Center: Build 11.00.01.01.1011 (Build 6)
• SBM Composer : 11.0.1.1 (Build 0006)
• SBM System Administrator and SBM Application Administrator: 11.00.01.00.1011 (Build 6)
• Application Repository: Build 11.00.01.01.1011 (Build 6)
• SBM Configurator: 11.00.01.01.1011 (Build 5)
• Database version: 1101010001

Third-Party Tools

For more information regarding third-party software copyrights and license information, refer to the files under "Downloads" or "News" at http://www.serena.com/support.

Supported Upgrade Paths

• Upgrading from 2009 R4 or later

  If you are upgrading from 2009 R4 or any version thereafter, refer to the important notes and instructions below to upgrade to SBM 11.0.1.1.

• Upgrading from versions prior to 2009 R4

  If you are upgrading from a version of SBM prior to 2009 R4, follow the upgrade instructions in solution S138037 to upgrade to 10.1.5.X first, and then upgrade your 10.1.5.X installation to SBM 11.0.1.1 using the instructions below.

• Upgrading from TeamTrack 6.6.1.X

  If you are upgrading from TeamTrack 6.6.1.X, follow the instructions in the Moving to Serena Business Manager guide (available at http://www.serena.com/support) to upgrade to SBM 10.1.5.X first. In addition refer to solution S137372 to learn about the upgrade preparation utility. After you have upgraded TeamTrack to SBM 10.1.5.X, follow the instructions below to upgrade to SBM 11.0.1.1.

• Upgrading from Tracker

  For information on migrating your Tracker data to SBM, refer to the "Migrating Tracker Data to SBM" solution (S138468).

Requirements and Changes

Before you upgrade to SBM 11.0.1.1, read the following important information:

• SBM 11.0.1.1 requires Serena License Manager 2.2. You must upgrade to version 2.2 before you can upgrade to SBM 11.0.1.1. .
• SBM 11.0.1.1 requires 64-bit Windows servers. If you are using 32-bit servers prior to the upgrade, you must install SBM 11.0.1.1 on one or more 64-bit machines, and then upgrade the databases using the 64-bit installation. As part of the upgrade, review and upgrade any scripts and APIs that were originally created on a 32-bit operating system to ensure that they also run on a 64-bit system. For example, if you have any scripts that load .dll files, those .dll files must be upgraded to run on a 64-bit machine.
• In order to prevent notifications from being sent for changes that have not happened recently, SBM now deletes notification events that are older than 90 days that contain a THREADID during the database upgrade. To check if you have events that will be deleted, refer to the SQL queries in solution S140945.
• Work Center search operates on pre-built indices that may change for each SBM release. The Work Center search index is rebuilt when Tomcat is started for the first time after the upgrade. The complete indexing operation can take ample time to finish for very large databases; however, some search results in Work Center begin to appear immediately and the number of results continues to grow while the initial indexing operation works toward completion.

  You can view the overall progress of the indexing operation in the ssf.log file located on the server that hosts SBM Common Services. The log file is located here:

  installDir\Serena\SBM\Common\Tomcat 7.0\server\default\logs

• As part of the database upgrade and migration to the new ODE BPEL engine, data in the CL_CONTEXT_VALUE and CL_LOG tables is deleted. New indexes are added to the CL_CONTEXT_VALUE and CL_LOG tables on upgrade to prevent time outs from occurring when you try to view Common Log data in SBM Composer or SBM Application Repository. In order to add the new indexes, these tables will be emptied during the upgrade process.
  Important: If you need to view Common Log data that was present prior to the upgrade, ensure that you have backed up these tables.
• For Oracle systems, note the following:
  • You must ensure that the required roles and privileges for the SBM schema user are up-to-date. Refer to solution S133641 for details.
  • You must perform the database upgrade using either the SBM DSN or a system DSN that uses the "Oracle for SBM" driver. If your system used the Mashup2009 DSN prior to the upgrade, that DSN is automatically converted to use the new "Oracle for SBM" driver.
    Important: The underlying driver in the DSN that ships with SBM was changed in SBM in 10.1. If you currently use the Mashup2009 DSN with SBM, you do not need to do anything—the DSN will be updated automatically. If you created your own custom DSN with the "Oracle for SBM" driver prior to upgrading to SBM 10.1 or later, then you must recreate the DSN and use the new "Oracle for SBM" driver that ships with SBM after the upgrade is finished.

Planning for the Upgrade

The upgrade process you will follow depends on the type of installation you currently have:

• Single Server Installation — All of the SBM components are installed on a single server.

  For single server installations, you will run the suite installer on your server and then upgrade the databases using SBM Configurator. The databases are upgraded in two phases—in phase one, the Application Engine database is upgraded; once it completes successfully, phase two begins. In phase two, you are prompted to enter the SBM user name and password of your primary system administrator or an SBM user that has the Remote Administration privilege to upgrade the Orchestration Engine database.

• Distributed Installation — The SBM components are installed on multiple servers that comprise a single production environment.

  For distributed installations, you will run the suite installer on each server, and then use SBM Configurator to upgrade the databases. When you begin the Orchestration Engine database upgrade on the server that hosts SBM Orchestration Engine, you are prompted to enter the SBM user name and password of your primary system administrator or an SBM user that has the Remote Administration privilege. This scenario requires that you start the SBM services and that you perform the database upgrades in a certain order. This is explained in more detail below in Upgrading the Databases.

• Multi-environment installation — The SBM components are installed on single or multiple servers that are separated into multiple SBM environments (such as development, test, and production).

  The process for upgrading multiple environments (used in a path to production model) depends on which environment hosts SBM Application Repository and which environment you plan to upgrade first (Test/Staging first or Production first).

  • If SBM Application Repository is part of the Test environment and you plan to upgrade Test first

    In this setup, each environment uses a single instance of Application Repository that is installed in the Test environment. You will upgrade the Application Engine and Orchestration Engine databases in the Test environment first. After the upgrade in Test is finished, you will not be able to deploy to Production from Application Repository until you upgrade the Production servers and databases.

  • If SBM Application Repository is part of the Production environment and you plan to upgrade Test first

    In this setup, each environment uses a single instance of Application Repository that is installed in the Production environment. You will upgrade the Application Engine and Orchestration Engine databases in the Test environment first. After the upgrade in Test is finished, you will not be able to deploy to Test from Application Repository until you upgrade the Production servers and databases.

    Important: If you are upgrading from 2009R4X, in order to upgrade the Test environment first, you must install and configure a temporary 11.0.1.1 instance of SBM Application Repository that is connected to a backup copy of the production Application Repository database. Once the upgrade in the Test environment is finished, you can uninstall the temporary 11.0.1.1 SBM Application Repository instance and delete the backup copy of the database that was used for the upgrade.
  • If SBM Application Repository is part of either Production OR Test and you plan to upgrade all environments at the same time

    If you plan to upgrade all environments at the same time (one immediately after the other), upgrade the instance that hosts Application Repository first (likely Production). This will allow you to upgrade the other environments that do not have SBM Application Repository without installing a temporary instance.

  For information about warnings that may appear during a multi-environment upgrade, see Handling Warnings with Multiple Environments.

If you are upgrading from the following versions, plan for hosting new server components as follows:

• If you are upgrading from 09R4, you will use SBM Configurator to designate which server or servers will host the SBM Mail Services component. By default, SBM Mail Services appears on an undefined server until you drag and drop it to the desired server or servers.
• If you are upgrading from a release prior to 10.1.2, use SBM Configurator to designate which server will host the SBM Logging Services component. By default, SBM Logging Services appears on an undefined server until you drag and drop it to the desired server. If you are upgrading from a release after 10.1.2, SBM Logging Services is enabled on the same machine as SBM Common Services by default. You can use SBM Configurator to move it to a dedicated server, if necessary (for example, if you set the logging level to TRACE for debugging purposes).

Pre-Upgrade Steps

Follow these steps before you perform the upgrade.

1. Verify that SBM 2009 R4 or later is installed on the System Information tab in SBM Configurator.
2. Back up your existing databases.
3. Back up the SBM installation directory structure on the Application Engine server.
4. Back up the Smart Search index directory on the SBM Common Services server. If you need to revert the upgrade for any reason, you will restore the index from this backup (because the index is rebuilt as part of the upgrade).
5. Consider consulting with your DBA to assess the current table indexes in the SBM databases. Because significant database schema changes do not necessarily coincide with each database upgrade, table indexes are not automatically rebuilt as part of the upgrade process. Over time, indexes can report excessive fragmentation, which could negatively impact performance if they are not rebuilt periodically.
6. If you store SBM item attachments on the file system, open SBM System Administrator and note the location of the attachments directory. You will enter the location in SBM Configurator later as part of the upgrade.
7. Create a new database space in your DBMS to host the Configuration Settings database if you did not create it in a prior release. As of SBM 10.1.5, you can use this database to store configuration settings across your entire SBM installation in one centralized location.
8. Download the new suite and client installers from support.serena.com.

Upgrading the Installation

Upgrading the Databases

The database upgrade process has changed as of SBM 11.0. Review the following important information before you begin.

• The Orchestration Engine database upgrade is no longer automatically performed after you start the SBM services; instead, you must manually invoke the upgrade process by clicking the Upgrade Database link in SBM Configurator. This ensures that the Orchestration Engine database is not upgraded prematurely.
• If SBM Application Engine and SBM Orchestration Engine are installed on the same server, the Orchestration Engine database upgrade is performed immediately after the Application Engine database upgrade.
• If SBM Application Engine and SBM Orchestration Engine are installed on separate servers:
  • You must ensure that IIS is started on the SBM Application Engine server and SBM Tomcat is started on each of the other SBM servers. Both IIS and SBM Tomcat must be running and all components must be accessible from the SBM Orchestration Engine server before the Orchestration Engine database upgrade begins.
  • You must upgrade the Application Engine database on the SBM Application Engine server first, and then upgrade the Orchestration Engine database on the SBM Orchestration Engine server.
• The Orchestration Engine database upgrade is performed by the renew utility using the user account that you specify when prompted. For details on this process and more information related to the Orchestration Engine database upgrade, refer to About the Orchestration Engine Database Upgrade.

When you are ready, open the Database Servers tab in SBM Configurator, and then click Upgrade Database.

installDirectory\Serena\SBM\Application Engine\log

If an ORA-00904 message appears in the Application Engine upgrade log after you finish upgrading the Application Engine database, refer to solution S141358 for a description of the problem and a resolution.

After the databases are upgraded successfully, verify that the services are started in the Manage Services tab. Instruct Application Repository users to clear the cache in their Web browsers before they attempt to access SBM Application Repository.

Post-Upgrade Tasks

Review the following information and make any necessary changes after you have upgraded your servers and databases:

• SBM Configurator warns you if your installation currently uses default certificates (which should be replaced) or if your current certificates will expire soon.
  Important: To properly secure your installation, you must generate new key pairs even if you do not plan to use SSO. If you do not generate new key pairs, then the default certificates that the STS inherently trusts are used. To increase security, launch SBM Configurator and generate new unique certificate for all components. For details, see "Securing SBM" in the SBM Installation and Configuration Guide.
• If you encrypted SSO passwords prior to the upgrade, you must re-encrypt the passwords using the Security tab in SBM Configurator after the upgrade is finished on the SSO server. This ensures that the SSO passwords in the gatekeeper-core-config.xml file remain encrypted.
• For systems that are configured to use client certificate authentication, you must perform additional configuration steps after the upgrade or disable the feature entirely. For details, refer to the entry about client certificate authentication in Installation and Configuration Issues.
• HTML rendering and Rich Text editing is enabled by default for all notes in your system after the upgrade. To disable these features for notes, clear the Render HTML in Notes check box located on the HTML tab of the Settings dialog box in SBM System Administrator.
• As part of the upgrade from any version prior to 11.X, SBM reviews the existing JBoss configuration and allocates the same amount of memory to Tomcat that was previously allocated to JBoss. After the upgrade, if you need to adjust the amount of memory that is allocated to Tomcat, perform the following steps:
  1. Stop the SBM Tomcat service.
  2. Navigate to installDirectory\Serena\SBM\Common\Tomcat 7.0\bin, and edit the common_config.bat file.
  3. Change the JVM_X_MAXMEMSIZE value as necessary.
  4. In the same \bin directory, execute the update_tomcat_config.bat file.
  5. Start the SBM Tomcat service.
• After the database upgrades are finished, use the Reset Administrative User Access wizard in SBM System Administrator if your database does not contain at least one Regular User or Managed Administrator account with Remote Administration privilege. This wizard enables you to define at least one user as your primary system administrator (an account that has Regular User or Managed Administrator product access with Remote Administration privilege) who can log in to SBM Application Administrator. For details, see the SBM System Administrator Guide.
• User credentials in SBM Application Engine Web service calls that use Basic authentication are now handled exclusively by SBM Application Engine itself, instead of IIS. This configuration is common if your SBM system is set up with NT Challenge Response for end-user authentication. After upgrade, this means that you must now specify the Windows domain for Web service calls in SBM Configurator, otherwise the domain that the IIS server machine is installed on is used for user validation.
• The use of logical field names in the $FIELDVALUE base item template tag is deprecated and will not be supported in future releases. Serena recommends that you review your current e-mail templates and replace field display names with the database field name after the upgrade.

Upgrading Customizations and Integrations

Review the following information for help with upgrading custom changes and integrations.

• If you made custom modifications to any HTML templates, e-mail templates, or online help files, you must merge your changes into the newly-upgraded files, and then use SBM System Administrator to Put Files in Database. All templates and images in the database are replaced by files on your local machine as part of this operation. Backup templates are stored on the installationDirectory\Serena\SBM\Application Engine server here:

  installDir\Serena\SBM\Application Engine\Backup<version>-<date>-<time>

  Note: For a list of configuration Files, Web Interface templates, JavaScript files, and strings that have changed in 11.0.1, refer to solution S141605. You must manually merge some of your existing SSO customizations into the newly installed files after you upgrade your software and database.

  If you used custom HTML templates in your reports, the reports might not display properly after upgrade. Consider using the default template or modifying it as needed instead. For example, as of SBM 10.1.2, several changes were made to Summary Reports that might not display properly using a custom template from a prior release. Instead, either use the new default template or merge your changes into the default template to create a new custom template.

• If you installed the TT4ZMF integration prior to upgrading, you must follow the instructions in the TT4ZMF readme to reinstall the integration after the SBM upgrade is complete.
• In SBM 10.1.2, the SSO Login Application (Federation Server) was merged with the SSO Security Token Service (STS) into a single SSO Security Server (also known as the Identity Provider (IDP)). This means that the ALFSSOLogin.war and TokenService.war directories were been merged and replaced with a new idp directory on the SSO server.

  If you are upgrading from a release prior to 10.1.2 and you have created custom SSO integrations, you must review all URLs and calls to ensure that they use the latest directory names. For example, if your existing integrations call the Security Token Service (STS), you must ensure that the new idp directory is used.

  The endpoints of the SSO services must be changed accordingly. The relative URIs will stay the same, but since the application is new, the login application entry point will be http(s)://host[:port]/idp/login. For the STS, it will be: http(s)://host[:port]/idp/services/Trust.

• If you configured your system to use anonymous events prior to the upgrade, you must either add credentials to your events (preferred) or you must select the Allow Anonymous Events check box in SBM Configurator and enter an SBM user name and password to use anonymous events after the upgrade.

Orchestration Engine Database Schema Changes

The Orchestration Engine database upgrade is now performed by the renew utility that is installed with SBM. (For detailed information about the renew utility, refer to the SBM Orchestration Guide.) The renew utility is responsible for restoring existing data in the JBPM tables into the new BPEL tables that are used by the Apache ODE BEPL engine. Existing data in the event manager tables is preserved to ensure that orchestrations continue to run as they did prior to the upgrade.

The JBPM and JMS tables in the database are not dropped as part of the upgrade, but they are no longer used and do not conflict the new BPEL tables that are added. If you want to remove the old JBPM tables after the orchestration database has been successfully upgraded, on the server that hosts SBM Orchestration Engine, run the clear_jbpm.bat file located here:

installDirectory\Serena\SBM\Common\Misc\renew\renew_templates\clear_jbpm.bat

Retrying Orchestration Engine Upgrades and Clearing Warnings

When the renew utility is launched, all process apps that contain orchestrations are redeployed. If any failures are encountered, a message appears and presents the following options:

• View Warnings

  This opens the fail_out.xml file located here:

  installDirectory\Serena\SBM\Misc\renew\fail_out.xml

  This file contains a list of process apps that failed to upgrade successfully and target environments that are invalid.
• View Log

  This opens the upgrade.log file located here:

  installDirectory\Serena\SBM\Common\Tomcat 7.0\server\default\logs

  This file contains details about the upgrade, including detailed error messages for any failures that were encountered.

Use the list in fail_out.xml in combination with the detail from the upgrade.log to investigate any failures. Depending on the failures, you have the following options:

• You can address the failures, and then click Upgrade Database again. In the prompt that appears, click Retry Upgrade. This launches the renew utility again and attempts to deploy your process apps now that the failures should be fixed.
• If the failures are expected and you do not want to change anything, click Upgrade Database again in SBM Configurator, and then click Clear Warnings in the prompt that appears. This prevents the warnings from appearing again and completes the database upgrade.

For example, if the schema version in a process app needs to be upgraded, NOT_SUPPORTED_VERSION appears as the cause in the fail_out.xml file. This means the process app schema version needs to be upgraded by redeploying from SBM Composer. You can either redeploy from SBM Composer and run the database upgrade again, or if you do not want to redeploy at this time, but you want to finish the database upgrade now, click Upgrade Database again, and then click Clear Warnings.

The database upgrade will report failures if the target server information in your environments is missing or cannot be verified. For example, if you are testing the production database upgrade by moving the database to a different environment, the upgrade process will report failures related to your environment definition in Application Repository. You can either update the endpoint and target server information and click Retry Upgrade or click Clear Warnings to proceed without making the changes to finish the upgrade.

-redeployInFile fail_out.xml

-failOutputFile fail_out.xml

Handling Warnings with Multiple Environments

In multi-environment installations, the renew utility attempts to redeploy process apps that contain orchestrations to every SBM environment in Application Repository. If you have three environments defined, when you upgrade the first environment (Test, in this example), messages appear in the upgrade.log about skipping the other environments that have not been upgraded:

Redeployment will be skipped for ‘Staging Environment’ environment since it is not upgraded. AE version 10.01.05.02.115
Redeployment will be skipped for ‘Production Environment’ environment since it is not upgraded. AE version 10.01.05.02.115

You can safely ignore these messages because you will upgrade these environments in turn.

When you prepare to upgrade each subsequent environment, consider stopping the SBM Tomcat service first in your upgraded environments to prevent redundant redeploy operations from occurring. Stopping SBM Tomcat in each upgraded environment also speeds up the overall upgrade process. However, note that failures will be recorded in the fail_out.xml for these environments because the upgrade will still attempt to redeploy to them. If the only failures that appear are related to the environments that have already been upgraded, use the Clear Warnings button to discard these warnings and finish the upgrade. In this scenario, this enables SBM Configurator to consider the Test database upgrade as “complete” because the warnings do not apply to the current environment and the Test database was successfully upgraded.

Resolving WSDL Validation Errors

Validation errors appear during the SBM Orchestration Engine database upgrade if the process apps that are redeployed by the renew utility contain WSDLs that fail WS-I validation. The same validation failures appear when you attempt to deploy process apps with invalid WSDLs in 11.0.X. This is due to the change from the JBPM to Apache ODE engine in 11.0, which follows new rules to ensure that SBM does not allow execution of invalid WSDLs.

If a WSDL validation failure is encountered, you can view the WSDL in either SOAP UI or Eclipse to find the invalid portion and fix it accordingly. After you have modified the WSDL and ensured that it passes WS-I validation in either tool, modify the process app .msd file, replace the invalid WSDL file with the fixed version, and then redeploy the process app.

For more information and troubleshooting tips on resolving WSDL validation errors, refer to solution S141405.