Migration
You can migrate orders to TIBCO Order Management 6.1.0 (OM 6.1.0) from the following previous versions:
-
TIBCO® Fulfillment Order Management 4.0.2 HF-14 (FOM 4.0.2 HF-14)
-
TIBCO Order Management - Long Running 5.0.1 HF-6 (OM-LR 5.0.1 HF-6)
-
TIBCO Order Management 5.1.0 HF-8 (OM 5.1.0 HF-8)
-
TIBCO Order Management 6.0.0 HF-3 (OM 6.0.0 HF-3)
Database Details
To migrate the orders from the previous versions, the migrated_orders
table needs to be present in the previous versions order database. This table is generated after running the migration scripts in the following locations:
-
For PostgreSQL,
<OM_HOME>/db/dbscripts/migrationTo610/postgreSQL
-
For Oracle,
<OM_HOME>/db/dbscripts/migrationTo610/oracle
Configure the application properties file
Before starting, the Migration service gets the necessary configuration properties from the
Configurator component. Some properties, found in the <OM_HOME>/roles/om-migration/standalone/config/application.properties
file,
must be available for the server to start smoothly.
Property Name | Property Value | Description |
---|---|---|
server.port | 9100 | Port at which the Migration service starts |
configuratorServiceUrl | http://localhost:9090
|
Configurator base URL to connect and download configuration properties and configuration files |
configuratorServiceRetryCount | 5 | Number of retries to perform in case of request failure to Configurator |
configuratorServiceRetryDuration | 5 | Delay between each retry, in seconds |
configuratorTrustStoreAbsoluteFilePath | C:/Users/cacert | Trust store file path if the Configurator is on HTTPS |
configuratorTrustStorePassword | tibco123 | Trust store password if the Configurator is on HTTPS |
configuratorTrustStoreType | jks | Trust store type if the Configurator is on HTTPS |
security.key | ENC(nSa0k6lmjPPN8ZA5SO6BpQ==) | Security key to securely connect to Configurator. The default value is encrypted of 1t1s@asy |
Configure the configuration values for migration file
The Configurator must have specific configuration properties. These properties, found in the <OM_HOME>/seed-data/app-properties/ConfigValues_Migration.JSON
file, must be uploaded to the configuration before the server starts.
Archival Database Configurations for 6.1.0 Application
The Migration service moves orders to an Archival database using the specified database configurations.
Property Name | Property Value | Description |
---|---|---|
archivalDatasourceDriverClassName | org.postgresql.Driver | Archival Data Source Driver Name |
archivalDatasourceValidationQuery | SELECT 1 | SQL query that is used to validate connections |
archivalDsInitialSize | 10 | Number of connections that are established when the connection pool is started |
archivalDsMaxActive | 100 | Maximum number of active connections that can be allocated from this pool at the same time |
archivalDsMaxIdle | 100 | Maximum number of connections that must be kept in the idle pool |
archivalDsMaxWait | 10000 | Maximum number of milliseconds that the pool waits when there are no available connections |
archivalDsMinIdle | 100 | Minimum number of connections that must be kept in the idle pool |
archivalDsPassword | ENC(0yIDLwbMh07VvOWs4tFwDA==) | Data Source Password |
archivalDsTestOnBorrow | true | Enable connection validation before being borrowed from the pool |
archivalDsUrl | jdbc:postgresql://localhost:5432/
|
Data Source URL |
archivalDsUsername | archivaluserll | Data Source Username |
archivalDsValidationInterval | 5000 | Data source validation interval in milliseconds |
archivalHibernateDialect | org.hibernate.dialect.PostgreSQLDialect | Hibernate Dialect |
archivalHibernateDsDefaults | false | Enable Hibernate Metadata Defaults |
archivalHibernateShowSql | false | Hibernate Show SQL |
Order Data Source Configuration
The Migration service migrates orders from FOM 4.0.2 HF-14, OM-LR 5.0.1 HF-6, OM 5.1.0 HF-8, and OM 6.0.0 HF-3 using the following database configurations.
Property Name | Property Value | Description |
---|---|---|
omsDsDriverClassName | oracle.jdbc.driver.OracleDriver | Data source driver class name |
omsDsInitialSize | 10 | Number of connections that are established when the connection pool is started |
omsDsMaxActive | 100 | Maximum number of active connections that can be allocated from this pool at the same time |
omsDsMaxIdle | 100 | Maximum number of connections that must be kept in the idle pool |
omsDsMaxWait | 30000 | Maximum number of milliseconds that the pool waits when there are no available connections |
omsDsMinIdle | 100 | Minimum number of connections that must be kept in the idle pool |
omsDsPassword | ENC(iuGvcNQz8iS3QS1kSVGuwA==) | Data source password |
omsDsTestOnBorrow | true | Enable connection validation before being borrowed from the pool |
omsDsUrl | jdbc:oracle:thin:@//localhost:1521/orcl.apac.tibco.com
|
Data source URL |
omsDsUsername | tenantpdb | Data source Username |
omsDsValidationInterval | 5000 | Data source validation interval in milliseconds |
omsDsValidationQuery | select 1 from dual | SQL query that is used to validate connections |
omsHibernateDialect | org.hibernate.dialect.Oracle10gDialect | Hibernate dialect |
omsHibernateDsDefaults | false | Enable hibernate metadata defaults |
omsHibernateShowSql | false | Hibernate show SQL |
Admin Data Source Configuration for Legacy Application
The Migration service migrates orders from either FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6. The required configuration for the admin database are given in the following table.
Property Name | Property Value | Description |
---|---|---|
adminDatabaseDriver | oracle.jdbc.driver.OracleDriver | Data source driver class name |
adminDatabaseUrl | jdbc:oracle:thin:@//localhost:1521/orcl.apac.tibco.com
|
Data source URL |
adminDatabaseUsername | Admin Data Source Username | adminpdb |
adminDatabasePassword | ENC(GakyNNVqkpgAGrpT+ex7Ig==) | Data source password |
Messaging Configuration
The Migration service maintains a connection to the EMS server to process orders using the following configurations.
Property Name | Property Value | Description |
---|---|---|
emsServerPassword | ENC(T9aNk07NMsU=) | EMS server password |
emsServerURL | tibjmsnaming://localhost:7222
|
EMS server URL |
emsServerUsername | admin | EMS server username |
omsOrdersSequencerSubmitOrder | tibco.aff.oms.ordersSequencer.submitOrder | Submit order sequencer queue |
omsOrdersSequencerSubmitOrderReceiveTimeout | 1000 | Submit order sequencer queue receive TimeOut in milliseconds |
securityProtocol | For SSL configuration, the value must be ssl
|
|
sslEnableVerifyHost | For SSL enable, the verify host value must be false | |
jndiConnectionFactory | GenericConnectionFactory | JNDI connection factory |
Migration Functional Configuration
Functional configurations for the migration service are given in the following table.
Property Name | Property Value | Description |
---|---|---|
com.tibco.archival.order.udf.searchkeys | * | Frequently searched Order UDF names in ordersByCriteria API |
com.tibco.archival.orderline.udf.searchkeys | * | Frequently searched Order Line UDF names in ordersByCriteria API |
com.tibco.fom.orch.enableMilestoneReleaseDuringActivation | true | Enable Milestone Release during activation |
com.tibco.fom.orch.enableOrderSequencing | false | Enable the migration of sequenced orders from 5.0.* Application |
com.tibco.offlineMigration.migrateOrderInFinalState | false | Enable migration of orders in final state |
com.tibco.oms.legacy.tenantId | TIBCO | 5.0.* Application Tenant ID to consider for order migration |
enableAuditTrail | true | Enable migration of audit trail |
enableLegacyMigration | true | Enable eigration from legacy (LR) version |
Order Data Source Configuration for 6.1.0 Application
Database configurations for the 6.1.0 application are as follows.
Property Name | Property Value | Description |
---|---|---|
orderDatasourceDriverClassName | org.postgresql.Driver | Data source driver class name |
orderDatasourceValidationQuery | SELECT 1 | SQL query that is used to validate connections |
orderDsInitializeSize | 10 | Number of connections that are established when the connection pool is started |
orderDsMaxActive | 100 | Maximum number of active connections that can be allocated from this pool at the same time |
orderDsMaxIdle | 100 | Maximum number of connections that must be kept in the idle pool |
orderDsMaxWait | 10000 | Maximum number of milliseconds that the pool waits when there are no available connections |
orderDsMinIdle | 100 | Minimum number of connections that must be kept in the idle pool |
orderDsPassword | Data Source Password | ENC(A9fTymcpAOSVjnpb6jkvjA==) |
orderDsTestOnBorrow | false | Enable connection validation before being borrowed from the pool |
orderDsUrl | jdbc:postgresql://localhost:5432/ |
Data source URL |
orderDsUsername | orderdsuserll | Data source Username |
orderDsValidationInterval | 5000 | Data source validation interval in milliseconds |
orderHibernateDialect | org.hibernate.dialect.PostgreSQLDialect | Hibernate dialect |
orderHibernateDsDefaults | false | Enable hibernate metadata defaults |
orderHibernateShowSql | false | Hibernate show SQL |
Before you begin the migration
The messages, corresponding to the in-process orders in the previous versions, are not allowed to remain in the pending state on the queues mentioned in the following section. These messages must be processed before upgrading. However, there are a couple of queues on which messages can remain pending.
-
Stop the northbound system (for example, Siebel CRM), which sends the order request messages to TIBCO Order Management for fulfillment. Doing this ensures that there are no new order messages coming on the
tibco.aff.oms.ordersService
queue. All the existing messages must be processed by the OMS server component. -
Stop the southbound process component systems, which are integrated with Order Management for processing various requests for plan items, such as execute request, suspend request, activate request, and milestone release request. Doing this ensures that there are no messages pending on the following queues:
-
tibco.aff.orchestrator.planItem.execute.reply
-
tibco.aff.orchestrator.planItem.suspend.reply
-
tibco.aff.orchestrator.planItem.milestone.notify.request
-
tibco.aff.orchestrator.planItem.suspend.request
All the existing messages must be processed by the OMS server component in the older version of the product from where you are migrating.
Ensure that there are no new messages coming from process components on the following queues associated with the JMS-based data access interfaces, which are used to get the order data and get or set the plan/plan item data:
tibco.aff.tds.order.read.request
tibco.aff.tds.plan.request
tibco.aff.tds.plan.read.request
All the existing messages must be processed by the OMS server in the older version of the product from where you are migrating.
-
-
Ensure that there are no messages pending on the following queues related to the various types of order requests submitted to the Orchestrator:
tibco.aff.orchestrator.order.suspend
tibco.aff.orchestrator.order.activate
tibco.aff.orchestrator.order.withdraw
-
If the order feasibility check is enabled in the Orchestrator configuration, ensure that there are no messages pending on the following queues:
tibco.aff.orchestrator.provider.order.feasibility.request
tibco.aff.orchestrator.provider.order.feasibility.reply
The external feasibility provider component must process all the request messages and the Orchestrator must process all the reply messages.
-
Ensure that there are no messages pending on any of the following queues that are used for the integration between Orchestrator and the AOPD components for execution plan generation:
tibco.aff.orchestrator.provider.order.opd.request
tibco.aff.orchestrator.provider.order.opd.reply
-
If order prequalification handling is enabled in the Orchestrator configuration, ensure that there are no messages pending on the following queues:
tibco.aff.orchestrator.provider.order.prequal.failed.request
tibco.aff.orchestrator.provider.order.prequal.failed.reply
The external prequalification failed request handler must process all the request messages and the Orchestrator must process all the reply messages.
-
Ensure that there are no messages pending on any of the following queues that are used for integration between Orchestrator and the external plan item error handler component for processing the failed plan item requests:
tibco.aff.orchestrator.provider.planItem.failed.request
tibco.aff.orchestrator.provider.planItem.failed.reply
Considering the pending messages on all the earlier mentioned queues are processed by the respective components of the previous versions.
Messages can be pending on the following queues. These are the outbound queues for the Orchestrator to send various requests for plan items to the process components. The messages on these queues are processed once the process component systems are started after the upgrade.
tibco.aff.orchestrator.planItem.execute.request
tibco.aff.orchestrator.planItem.suspend.request
tibco.aff.orchestrator.planItem.activate.request
tibco.aff.orchestrator.planItem.milestone.release.request
If the requestReply
header property is set to false in the GetOrder, GetPlan, GetPlanItem, SetPlan, or SetPlanItem data access requests, there can be pending messages on the following queues:
tibco.aff.tds.order.reply
tibco.aff.tds.plan.reply
If the requestReply
header property is set to true, messages can be pending on the queues passed as replyTo destinations in the requests. These are also the outbound queues for the OMS server and the pending messages on these queues are also processed once the process component systems are started after the upgrade.
After ensuring that no further processing is going on in any of the servers of the older version of the product from where you are migrating, they can be shut down. Also, shutdown all the external components, such as feasibility provider, pre-qualification failed request handler, external OPD, and plan item error handler component.
Backing up the EMS Messages
You must back up the pending EMS messages when you are migrating from any of the versions.
Installing TIBCO Order Management 6.1.0
Download the TIBCO Order Management 6.1.0 build from TIBCO eDelivery and extract the TIB_om_6.1.0_debian.zip
or TIB_om_6.1.0_rhel.zip
file to the OM_HOME folder. For more information, see
"Installation and Deployment" of the TIBCO® Order Management Installation and
Configuration.
You cannot migrate orders that are in OPD status. To migrate such orders, ensure that the orders have passed the OPD state.
When the same order ID is present in both Order Management - Long Running 5.0.1 HF-6/Fulfillment Order Management 4.0.2 HF-14 and Order Management 5.1.0 HF-8/OM 6.0.0 HF-3, the order of the latter gets replaced during migration.
Catalog is not migrated. You need to reload models on Order Management 6.1.0
All the above steps are mandatory for both online and offline migration. Once you have completed all the above mentioned steps, you can start the following services from Order Management 6.1.0:
-
Orchestrator
-
AOPD (Automated Order Plan Development)
-
Archival
-
DataService
-
OMS UI
-
Migration service
-
Catalog
Migrating Orders from Previous Versions to TIBCO OM 6.1.0
For migration, you can use any of the following procedures:
enableLegacyMigration
to false from the Migration service.Final Order
When the migrateOrderInFinalState
flag is true:
-
Final regular orders are converted from the previous versions order database and stored solely within the OM 6.1.0 Archival database.
-
For final amend orders, data is converted from the previous versions order database and stored in the OM 6.1.0 Archival database. Additionally, data are from the
order_amendment
table is retrieved, converted, and saved into the corresponding Archival amendment tables.
Offline Migration
This process is called offline migration because before you start using the Orchestrator from Order Management 6.1.0, you need to complete the migration. This is an on-demand process. You can choose which orders to migrate.
- Procedure
-
On the Configurator UI, navigate to Migration service > App properties.
-
Select the Admin Data Source Configuration for legacy Application category and provide admin database property details of the previous version from where the migration is done. For more information, see Admin Data Source Configuration for Legacy Application.
-
Select the Order Data Source Configuration category and provide the default tenant database property details of the previous version from where the migration is done. For more information, see Order Data Source Configuration.
-
Select the Messaging Configuration category and provide the property details of the previous version from where the migration is done. For more information, see Messaging Configuration.
Note: The current EMS and the previous (source) version must be the same. -
Select the Archival Database Configurations for 6.1 Application category and provide property details from the current database. For more information, see Archival Database Configurations for 6.1.0 Application .
-
Select the Order Data Source Configuration for 6.1 Application category and provide property details from the current database. For more information, see Order Data Source Configuration for 6.1.0 Application.
-
(Optional) Select a Migration Functional Configuration category and set the value of the
com.tibco.offlineMigration.migrateOrderInFinalState
flag as true to migrate the final state (CANCELED
,COMPLETE
) orders. For more information, see Migration Functional Configuration.
-
-
Navigate to the
$OM_HOME/roles/om-migration/standalone/config
directory and update theapplication.properties
file forconfiguratorServiceUrl
(value is the IP or DNS name of the Configurator service). -
To start the Migration service, navigate to the
$OM_HOME/roles/om-migration/stanalone/bin
directory and run the./start.sh
script. -
To access the Swagger REST API, enter the following endpoint in a browser:
http://localhost:9100
. -
Run the request to migrate orders from the following endpoints:
-
FOM 4.0.2 HF-14 or OM-LR 5.0.1,
/v1/lr/migration/order
-
OM 5.1.0 HF-8,
/v1/migration/orders
-
OM 6.0.0 HF-3,
/v1/migration/order
You can enter various criteria, such as
orderID
,orderRef
, anddateRange
.Sample
{ "orderID": "string", "orderRef": "string", "dateRange": { "startDate": "2024-09-12T15:11:50.366Z", "endDate": "2024-09-12T15:11:50.366Z" }, "status": [ "string" ], "headerUdfs": [ { "name": "string", "value": "string" } ], "orderLineUdfs": [ { "name": "string", "value": "string" } ] }
Request Schema Parameter Description orderID Order ID to be migrated orderRef Order reference of Order to be migrated dateRange Date range in between which all orders are to be migrated status Status of the order to be migrated headerUdfs UDF headers of order to be migrated orderLineUdfs Order line UDFs of order to be migrated This API handles migration of orders from FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 to OM 6.1.0
Request validations and corresponding error responses
-
If all search criteria are empty
{ "status": "BAD_REQUEST", "message": "All search criteria are either null or empty" }
-
Invalid search criteria
{ "status": "NOT_FOUND", "message": "No order that matches the given criteria is available to migrate." }
-
If the request is invalid
Error: response status is 400
Response Body
{ "migratedOrderIds": [ "string" ] }
Response Schema Parameter Description migratedOrderIds Order ids which are migrated Responses HTTP Status Description 200 Orders are migrated 208 Reported orders are already migrated 400 Bad request 401 Unauthorized request 404 Not found 500 Internal server error -
-
Start the other services. For more information, see "Task 10: Starting or Restarting the Services" of the TIBCO® Order Management Installation and Configuration guide.
-
Start the southbound system so that the Orchestrator service can start processing these messages.
-
Once you observe that the existing messages for the in-flight orders have been fulfilled by the Orchestrator, start the new incoming orders flow from the northbound system.
com.tibco.fom.orch.enableOrderSequencing
is set as true), the in-progress sequenced orders are migrated one by one to the Order database and Archival database with Order Status as Blocked.-
Based on the request, it migrates orders to OM 6.1.0 database in bulk or single order.
-
Based on the
enableAuditTrail
flag value, it migrates audit trail data. -
Based on the
migrateOrderInFinalState
flag value, it migrates orders in their final state.
Online Migration
This process is called online migration, because the in-flight orders from the source version can be processed in 6.1.0 version directly. You have to stop the services from the source version of the product to start the online migration process.
Online migration is performance intensive as the in-flight orders are migrated on the fly. For each in coming message processing from southbound, there is a call to the Migration service from Orchestrator.
- Procedure
-
On the Configurator UI, navigate to Order Management System > App properties.
-
Select the Migration Service Configurations category and set the
migrationURL
property as follows:-
For FOM 4.0.2 HF-14 or OM-LR 5.0.1,
http://<host>:9100/v1/lr/migration/order
. -
For OM 5.1.0 HF-8,
http://<host>:9100/v1/lr/migration/orders
. -
For OM 6.0.0 HF-3,
http://<host>:9100/v1/lr/migration/order
.
-
-
Once you configure these properties, restart the Orchestrator service.
-
Start the southbound system so that the Orchestrator service can start processing these messages.
-
Once you observe that the existing messages for the in-flight orders have been fulfilled by Orchestrator, start the new incoming orders flow from the northbound system.
Online-Offline Migration
Both the online and offline Migration services have their advantages and disadvantages. To overcome that, it is a best practice to use them together as per your requirements. For the in-flight orders, online migration is best suited. For orders that stay pending for a long duration, offline migration is more useful.
Troubleshooting for orders migrated from FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6
When you migrate orders from FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 to OM 6.1.0, the orders remain in EXECUTION even though pending messages are processed in OM 6.1.0.
For the workaround, you can perform the following steps:
-
Ensure Broker service awareness: Confirm that the Broker service recognizes the new Orchestrator instance, OM 6.1.0, and that it is properly configured to communicate with the new instance.
-
Register the FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 Instance: Register the FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 member id (originator) with the new Broker service. This instance does not communicate with the Broker service and eventually becomes inactive.
-
Monitor Inbound Queue: Once the FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 instance is inactive, the Broker service monitors the Orchestrator inbound queue for replies that include the originator header, using the member ID as the identifier.
-
Proceed with Migration: When waiting for the FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 instance to become inactive, continue migrating the orders.
-
Start the New Orchestrator: After the FOM 4.0.2 HF-14 or OM-LR 5.0.1 HF-6 instance is inactive, start the new Orchestrator and Process Component (PC) instance in OM 6.1.0 to ensure that message processing resumes properly.