Siebel CRM

Planning a Siebel CRM Upgrade: A Practical Checklist

By ··12 min read

Most Siebel upgrades that go wrong do not fail in the installer. They fail weeks later, on a gate nobody checked: an encryption level, a third-party jar compiled for an old Java, a certificate without the right key usage, an index owned by the wrong schema. This is the checklist our team works through before moving a Siebel CRM estate from an older Innovation Pack or update release to a current 25.x/26.x update.

1. Start with the upgrade path, not the installer

The first question is not "which installer?" but "which mechanism does Oracle document for my source version?" The Siebel Database Upgrade Guide contains a routing table, "Supported Upgrade Paths for Siebel CRM", and the answer depends entirely on where you are today. Check your actual repository version first: the guide notes that the repository version may not match the binary version.

-- Repository / schema version as the database sees it
SELECT APP_VER FROM <tableowner>.S_APP_VER;

The routing, as the 26.9 edition of the guide states it:

  • 7.5.3 to 7.7.2: new installation plus a two-step repository upgrade (to 8.1.1 first, then Incremental Repository Merge).
  • 7.8.2, 8.0, 8.1.1.0–8.1.1.7 (SEA), 8.2, 8.2.1: new installation plus a single-step repository upgrade: the classic Database Upgrade (upgrep, three-way repository merge, upgphys) directly to the current update.
  • 8.1.1.x and 8.2.2.x (SIA), 15.x, 16.x: migration installation plus Incremental Repository Merge (IRM) directly to the current update.
  • 17.0 or later (IP2017 onwards, 18.x–26.x): "Neither an Upgrade nor Incremental merge are required when applying a Monthly Update on any post-17.0 version."

That last row covers most estates we see today, and it changes the plan completely. For a 17.0+ source, upgrep, upgphys, the repository merge, IRM and the old dev2prod utility are the wrong tools. The documented flow is the update installer, then the PostInstallDBSetup utility on every database, the optional RepositoryUpdate utility in development, and the Siebel Migration Application to promote the repository to each runtime environment. The guide also describes Upgrade Factory, both cloud and on-premises. Its process runs the upgrep/upgphys path and needs a pre-IP2017 repository with an ancestor repository, so it does not apply to a 17.0+ source.

2. Inventory and baseline

You cannot validate an upgrade against a baseline you never recorded. Before anything is installed, capture the live configuration of the source enterprise and keep it with the project record:

# Run against the CURRENT enterprise and keep the output
srvrmgr -g <gateway_host>:<port> -e <enterprise> -u SADMIN -p '<password>' \
  -c "list component groups" -o old_component_groups.txt
srvrmgr -g <gateway_host>:<port> -e <enterprise> -u SADMIN -p '<password>' \
  -c "list named subsystems" -o old_named_subsystems.txt
srvrmgr -g <gateway_host>:<port> -e <enterprise> -u SADMIN -p '<password>' \
  -c "list parameters for server siebel-app1" -o old_server_params.txt
  • Hosts, ports, component groups, and the load balancer and session affinity setup.
  • Table owner, repository name and character set (from dba_users, S_REPOSITORY and NLS_DATABASE_PARAMETERS).
  • Application container tuning: heap and any custom Java options for every Tomcat. The update starts the containers from factory defaults.
  • Custom files in the Application Interface web root: browser scripts, CSS, images. Web templates have been repository objects since IP2017, so they move with the repository, not the filesystem.
  • Every inbound and outbound integration endpoint, every certificate, every truststore entry, and every cron job or script that touches Siebel.
  • A customization inventory: which standard objects you changed. Conflict review after RepositoryUpdate depends on knowing this.

3. Hard gates to clear before touching binaries

These items block the upgrade outright or cause failures that are expensive to unwind. We treat each one as a go/no-go check, per environment.

  • Certification matrix. The installation guides do not list OS, JDK and database client versions inline. They point to My Oracle Support KB871388 ("How to Check the Certification Matrix"). Also read KB825124 (Siebel CRM Update Guides and Known Issues) for the target release. Do not assume the platform you run today is still certified.
  • AES-256 encryption. The guide is explicit: if your encrypted data is not at a minimum of 256-bit AES, do not update to 25.10 or later. If the level is not known, copy FindCurrentEncryptionLevel.sh (or .bat on Windows) from the target image's Disk1/install folder to the old system and check siebsrvr/log/encryptupg.log.
  • Java 21 readiness. Current updates run on Java 21. Back up third-party jars before installing. Recompile custom Java classes with the Java 21 JDK and place them in applicationcontainer_internal/webapps/siebel/WEB-INF/lib before the container first starts. The installer overwrites server.xml, so back it up and reapply your changes afterwards.
  • Binary sort order in development. Siebel Tools cannot merge or update a repository on a database with non-binary NLS_SORT.
  • Indexes owned by another schema. This is a field lesson that cost our team a full day. If someone ever created an index on a Siebel table while connected as a different database account, the merge later fails with ORA-01418 or ORA-01408 on an index that visibly exists. USER_INDEXES will not show it.
-- Must return zero rows (run as the table owner)
SELECT OWNER, TABLE_NAME, INDEX_NAME, STATUS
  FROM ALL_INDEXES
 WHERE TABLE_OWNER = '<TABLEOWNER>' AND OWNER <> '<TABLEOWNER>';

-- Development databases must use binary sort order
SELECT PARAMETER, VALUE FROM NLS_DATABASE_PARAMETERS
 WHERE PARAMETER = 'NLS_SORT';
  • Custom indexes on EIM interface tables are dropped during the upgrade and not re-created. List them first.
  • Database memory for long single transactions. Workspace delivery after RepositoryUpdate runs as one large transaction. We have seen Oracle kill that session with ORA-04036 (PGA_AGGREGATE_LIMIT exceeded), and Siebel reported it only as SBL-DAT-00175 (database connection lost). Read the database alert log before suspecting the network.
  • Workspace history. WSCleanup is documented for databases where Composer Mode was enabled in IP16. It runs after the new binaries are installed and before the database update. Read what it does before you run it: it deletes repository records in every workspace other than MAIN and empties S_WORKSPACE, so undelivered work is lost.
  • Backups you have actually restored. The guide documents no partial rollback for PostInstallDBSetup, RepositoryUpdate or an incremental migration. Restoring from backup is the recovery plan.

4. Database update, repository update and migration

For a 17.0+ source, three utilities do the database-side work, each with a defined scope.

PostInstallDBSetup runs on every Siebel database (development and every runtime environment). It covers WSRanking, schema, seed and manifest import, workflow upgrade and task upgrade. The guide states it must complete before any Siebel component is used after the update. An in-place update can trigger it from the installer. A side-by-side install into a new directory goes through the installer's new-installation flow, so you run it yourself, from the new binaries, against the existing database:

# siebsrvr/bin/setup.ini holds SIEBSRVR_ROOT, ODBC_DSN, TBLO, TBLOUSER,
# SIEBUSER, SSE_ROLE, UNICODEDB, PRIMARY_LANG_CD, INDSPC, TBLSPC and
# GENERATE_SCHEMA (N = apply now, Y = generate DDL for the DBA, A = DDL already applied)
cd <siebel_root>
./PostInstallDBSetup -i siebsrvr/bin/setup.ini -p '<table_owner_password>' -z '<sadmin_password>'
echo $?

Read the exit code against the guide's table and do not wrap the command in a plain "fail on non-zero" check. Codes 0, 1 and 2 are success. 3 to 7 are failures (7 means it ran against a pre-IP2017 repository). 8 means it already ran for this version. Several other non-zero codes mean the run completed with a sub-process skipped or reporting a problem. Then read the HTML report under siebsrvr/log/PostInstallDBSetup_<timestamp>/. It lists schema, manifest and seed changes. On large repositories the workflow upgrade stage can run for a long time, so run the utility under nohup or tmux and plan the time for it.

If you are coming from a release between 20.8 and 22.6 and going to 22.7 or later, the guide calls for WFCleanup to fix duplicate workflow process names. If you skip it, workspace delivery or rebase can fail with DUPLICATE OBJECTS FOR TYPE 'Workflow Process'.

RepositoryUpdate runs once, in development only. The guide describes it as delivering optional repository changes made since 17.0, one payload folder per release. It records progress in S_WS_VERSION, so you never re-resolve conflicts you have already handled. It creates an integration workspace int_siebel_updateN under the parent you give it, plus a developer workspace under that for review. Run the Pre-Assessment first. It is a separate program, and it classifies incoming changes as critical (an attribute both Oracle and you changed) or informational:

java -jar MonthlyUpdate.jar -i <ini_file> -p '<table_owner_password>' -z '<sadmin_password>'

In Web Tools you can tick "Retain Customer Value" on individual report records, then run RepositoryUpdate against the same parent workspace with that report Id. Web templates do not merge, so reapply edits to standard templates by hand. After the update, the development schema has changed, and the next migration to each target carries that whole schema delta. A new index on a very large table can take hours, so schedule that first migration as a real maintenance window.

Siebel Migration Application promotes the repository. It replaces dev2prod, which is no longer supported. Each target must finish its own binary install and PostInstallDBSetup first. Migrations always run from development to each target, never chained, and runtime-to-runtime migration is not supported. A full runtime repository migration lands as a separate repository that you switch to explicitly, so you can abandon a bad one before cutover. An incremental migration applies directly, so take a backup immediately before every run.

5. Gateway, Application Interface, Tomcat and certificates

The binary side is where side-by-side installs earn their keep. The old install stays on disk as a reference and a fallback, and the new stack can be exercised fully before any user touches it. Items we check on every host:

  • Container tuning. Reapply the heap and Java options you recorded. The new containers start from defaults.
  • Web root content. Copy custom scripts, CSS and images into the new Application Interface web root on every AI host. Nothing in PostInstallDBSetup, RepositoryUpdate or the Migration Application copies filesystem content between directories.
  • Encryption key file. On a side-by-side Siebel Server, copy keyfile.bin into siebsrvr/admin/ from the environment that owns the database. A newly generated key file cannot decrypt existing data.
  • Named subsystems and parameters. If the new enterprise has a different name, its configuration does not carry over. Reapply the deliberate settings (integration endpoints, email, LDAP) and leave the rest at the new defaults. Do not copy every old parameter across.
  • Gateway passwords. The guide notes that passwords stored in the Gateway that were encrypted with RC4 are reset when the current release is installed. Plan to re-enter them.

Certificates need their own workstream. The Security Guide states that the Gateway requires client connections from the Application Interface to authenticate with a client certificate (mutual TLS). The AI certificate material must therefore carry both the serverAuth and clientAuth extended key usages. One combined certificate in a single keystore is the simplest option. The guide also documents separate server and client keystores, and recommends an internal CA for client certificates, because publicly trusted certificates may no longer include the client-authentication usage. Subject Alternative Names should be FQDNs, and every host that will talk TLS should be listed. Check the EKU after signing, not just in the CSR:

openssl req -in siebel.csr -noout -text | grep -A1 "Extended Key Usage"
keytool -list -v -keystore siebelkeystore.jks -alias <alias> | grep -A3 "ExtendedKeyUsages"

# Carry trusted CAs from the old truststore one alias at a time.
# Never -importkeystore: it would also copy any private key entry.
keytool -exportcert -keystore old_truststore.jks -alias <ca_alias> -file <ca_alias>.cer
keytool -importcert -keystore siebeltruststore.jks -alias <ca_alias> -file <ca_alias>.cer

Java 21 is also stricter about hostname verification on outbound calls. After one upgrade we saw outbound EAI fail with "No name matching <host> found" even though the CA was trusted. The target certificate had no SAN, and its CN did not match the hostname in the URL. Importing the certificate does not fix this. Before cutover, list every HTTPS outbound URL and compare each host against the certificate it presents:

echo | openssl s_client -connect <host>:<port> -servername <host> 2>/dev/null \
  | openssl x509 -noout -subject -ext subjectAltName

6. LDAP, SSO and BI Publisher

Authentication changes are easy to leave until the last week. Decide them early. For production users, the Security Guide recommends an LDAP security adapter. With SSO, the Object Manager flow does not change, and a trust token replaces the password. After the upgrade, confirm the LDAP named subsystems match what the old enterprise used. Do this on every adapter, not just the first one:

list params for named subsystem <LDAPSecAdpt> show PA_ALIAS, PA_VALUE

Named-subsystem changes are not picked up live, so restart the components that use the adapter. Then test a directory user login through each Object Manager. If the adapter talks LDAPS, the directory's CA must be in the trust configuration the Siebel Server uses.

BI Publisher (Oracle Analytics Publisher) is a separate stack, and it is often the last thing anyone tests. When it uses the Siebel security model, it validates every login, SADMIN included, through a Siebel web service call over HTTPS. The Java runtime that BI Publisher runs on must therefore trust the Siebel CA. A patch bundle that replaces that JDK also replaces its cacerts, so re-check the CA after every BI Publisher patch. The Reports Guide's LDAP integration steps finish by restarting the Siebel Server, the Gateway and BI Publisher. After that, test a report template upload and run a report. Also check that the XMLPReport component group is enabled where reports run.

7. Testing, cutover and rollback

Test through the URL users will actually use, behind the load balancer, not against a single node. Our minimum functional pass per environment covers these areas:

  • Business users (not SADMIN) log in, open their daily views, and create, save and re-query records in the main business objects.
  • Custom browser scripts work in the browser, with no 404s in the console. Files existing on disk is not enough.
  • Every inbound and outbound integration, one by one. Batch and EIM jobs run, and workflows fire.
  • Existing attachments open. A new attachment can be retrieved from a different Siebel Server.
  • Reports, document generation and printing.
  • Login and view response times are comparable to the old release.

Cutover readiness gate

Before the window opens, all of these must hold. Functional tests pass, with failures resolved, not just noted. A post-PostInstallDBSetup database backup exists and has been restored once. The old installation is untouched and can still start. The load balancer change can be applied and reverted in minutes. The rollback procedure is written, with a named decision-maker and an abort deadline. Business sign-off exists on the test results. There is a support rota for the first business day.

On the day, stop the old enterprise completely before starting the new one. Two enterprises writing to the same database is the one thing to avoid absolutely. Bring the stack up in order: Gateway registry, then the application containers, then the Siebel Servers. Prove each step with a process and listener check, because an exit code of 0 from a start script does not mean the service is running. Never kill -9 Siebel Server processes. The orphaned shared memory makes the next start fail with SBL-OSD-00220.

srvrmgr -g <gateway_host>:<port> -e <enterprise> -u SADMIN -p '<password>' \
  -c "list servers show SBLSRVR_NAME, HOST_NAME, SBLSRVR_STATE"

Be clear about what rollback means. Before users create data on the new release, rollback means pointing the load balancer back and starting the old stack. Even then, PostInstallDBSetup has already changed schema, seed and manifest, so prove on a non-production environment that the old release runs against the updated schema. After users create data, rollback means restoring the database and losing that data.

8. After go-live: validation and monitoring

The guide's post-upgrade tasks are short but easy to forget:

  • Review xtndobstbl.txt for custom extensions on obsolete tables, and re-implement any marked Inactive on their replacement table.
  • Validate dock objects and visibility rules with dictutl. The log should report no errors.
  • Reset any database parameters you changed for the upgrade window back to normal OLTP values, and manage statistics with dbms_stats.
  • Run a full Validate in Siebel Tools in batch mode against the updated repository.
  • Check license key activation with the License Key Activation utility (licensekeymodule.sh on UNIX).
dictutl /C <odbc_dsn> /U <username> /P '<password>' /D <tableowner> \
  /N "Siebel Repository" /A y 2> dictutl.log

Then watch the first days closely. Look for SBL- errors accumulating in Siebel Server logs, errors in the container catalina logs, and heap behavior under real load compared with the tuning you reapplied. Watch TLS handshake or PKIX failures from integrations you did not test, and component availability across every server. This is the visibility CoreOps was built to give. It runs with minimal dependencies alongside the enterprise and shows Siebel Server and component state with task utilization, Application Interface 5xx errors, and Siebel and Tomcat log errors grouped by error code, in one place, from the first hour after cutover.

Our team has run Siebel CRM upgrades since 2004, from classic upgrep merges to monthly update chains. Nearly every incident we have had to fix traces back to one item on this list that was assumed rather than checked. Write the checklist down, run it in every environment, and keep the evidence.

About the author

Written by Mahmoud Ali, CoretiTech. CoretiTech provides Siebel CRM support, upgrades and development, and builds CoreOps.

Contact us →
Planning a Siebel CRM Upgrade: A Practical Checklist | CoretiTech