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

Note: If you migrate the database from any previous version to the 6.1.0 version, you have to republish the catalog.

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/

archivaldbll?currentSchema=archivalschemall
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/

orderdbll?currentSchema=orderschemall
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.

Note: When you try to migrate the OPD, Feasibility, OPDERROR, or PQF orders, it gives an error in the log as the plan is not created. You must process all the pending messages from these queues before migration. Therefore the migrations for such orders are directly rejected and only the valid orders are processed.
Note: In OM 6.1.0, the plan item is not completed if its intermediate milestone is in pending state. You must notify milestone before migrating an order.
Note: Audit trails are migrated as is without any transformations.
Note: Complete all the amendments from the previous versions before migrating the orders.
  • 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.

Note:  

  • 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:

Note: Migration of orders from multi-tenant databases is supported without any configuration or restarting the services.
Note: Migration for Jeopardy and Order Messages is not supported.
Note: When you migrate orders from OM 5.1.0 HF-8 or OM 6.0.0 HF-3 to OM 6.1.0, you must set enableLegacyMigration to false from the Migration service.
Note: Migration is not suported for Microsoft SQL server.

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
  1. On the Configurator UI, navigate to Migration service > App properties.

    1. 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.

    2. 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.

    3. 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.
    4. 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 .

    5. 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.

    6. (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.

  2. Navigate to the $OM_HOME/roles/om-migration/standalone/config directory and update the application.properties file for configuratorServiceUrl (value is the IP or DNS name of the Configurator service).

  3. To start the Migration service, navigate to the $OM_HOME/roles/om-migration/stanalone/bin directory and run the ./start.sh script.

  4. To access the Swagger REST API, enter the following endpoint in a browser: http://localhost:9100.

  5. 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, and dateRange.

    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
  6. Start the other services. For more information, see "Task 10: Starting or Restarting the Services" of the TIBCO® Order Management Installation and Configuration guide.

  7. Start the southbound system so that the Orchestrator service can start processing these messages.

  8. 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.

ResultThe in-progress orders are migrated to the Order database and Archival database and the final state orders are migrated to the Archival database. If Order Sequencing is enabled (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
  1. On the Configurator UI, navigate to Order Management System > App properties.

  2. 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.

  3. Once you configure these properties, restart the Orchestrator service.

  4. Start the southbound system so that the Orchestrator service can start processing these messages.

  5. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.