Migrating orders to TIBCO® Order Management 6.0.0 or 6.0.0 HF-1

You can migrate orders from TIBCO® Fulfillment Order Management 4.0.2 HF-12 (FOM 4.0.2 HF-12), TIBCO Order Management - Long Running 5.0.0 HF-5 (OM-LR 5.0.0 HF-5), or TIBCO® Order Management 5.1.0 HF-7 (OM 5.1.0 HF-7) to TIBCO® Order Management 6.0.0 (OM 6.0.0), or TIBCO® Order Management 6.0.0 (OM 6.0.0) to TIBCO® Order Management 6.0.0 HF-1 (OM 6.0.0 HF-1) version by using any of the following processes.

Note: Migration of orders from multi-tenant databases is supported without any configuration or restarting the services.
Note: During the online migration, when the in-flight orders are being migrated, if a southbound notification arrives on the Orchestrator and order details are not present in the database, the order is not migrated by the migration service. Hence, the orchestrator cannot serve that notification.
Before you begin

This topic describes all the necessary steps that must be carried out before starting the migrating orders to TIBCO® Order Management 6.0.0.

The messages, corresponding to the in-process orders in TIBCO® Fulfillment Order Management 4.0.2 HF-12, TIBCO® Order Management - Long Running 5.0.0 HF-5, or TIBCO® Order Management 5.1.0 HF-7, are not be allowed to remain in the pending state on the respective queues. These messages must be processed before upgrading. However, there are a couple of queues on which messages are pending.

  1. Stop the northbound system (for example, Siebel CRM), which sends the order request messages to TIBCO® Order Management for fulfillment. Doing this, it ensures that there are no new order messages coming on the queue tibco.aff.oms.ordersService. All the existing messages must be processed by the OMS server component.

  2. Stop the southbound process component systems, which are integrated with Order Management for processing various requests for plan items such as run request, suspend request, activate request, and milestone release request. Doing this ensures that there are no new messages coming on the following queues. All the existing messages must be processed by the OMS server component.

    • tibco.aff.orchestrator.planItem.execute.reply

    • tibco.aff.orchestrator.planItem.suspend.reply

    • tibco.aff.orchestrator.planItem.milestone.notify.request

    This also ensures 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 from OMS. All the existing messages must be processed by the OMS server.

    • tibco.aff.tds.order.read.request

    • tibco.aff.tds.plan.request

    • tibco.aff.tds.plan.read.request

    Keep the TIBCO® Order Management components running for the appropriate time duration to let them process all pending messages associated with the in-flight orders on their inbound queues. The details for all the important queues are as follows:

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

      • tibco.aff.orchestrator.order.suspend

      • tibco.aff.orchestrator.order.activate

      • tibco.aff.orchestrator.order.withdraw

    2. If the order feasibility check is enabled in the Orchestrator configuration, ensure that there are no messages pending on the following queues. The external feasibility provider component should process all the request messages and the orchestrator should process all the reply messages.

      • tibco.aff.orchestrator.provider.order.feasibility.request

      • tibco.aff.orchestrator.provider.order.feasibility.reply

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

    4. If order prequalification handling is enabled in the Orchestrator configuration, ensure that there are no messages pending on the following queues. The external prequalification failed request handler should process all the request messages and the orchestrator should process all the reply messages.

      • tibco.aff.orchestrator.provider.order.prequal.failed.request

      • tibco.aff.orchestrator.provider.order.prequal.failed.reply

    5. 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 TIBCO® Fulfillment Order Management components, there are messages pending only 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 was set to false in the GetOrder, GetPlan, GetPlanItem, SetPlan, or SetPlanItem data access requests, there are messages pending on either of the following queues or 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.

      • tibco.aff.tds.order.reply

      • tibco.aff.tds.plan.reply

      After ensuring that no further processing is going on in any of the servers of TIBCO® Order Management, they can be shut down. Also, shutdown all the external components, such as feasibility provider, pre-qualification failed request handler, external OPD, component of the plan item error handler.

Backing up the Database

Since the upgrade involves changes in the database, make sure to back up the database instance that has been used by the previous version.

Installing TIBCO® Order Management 6.0.0

Download the TIBCO Order Management6.1.0 build from TIBCO eDelivery and extract the TIB_om_6.1.0.zip file to the OM_HOME folder. See Installation and Deployment.

Creating Databases

Create the databases for TIBCO Order Management6.1.0. See Task 2: Creating the Database

Upgrading the TIBCO EMS Channel

To upgrade the EMS channel from TIBCO® Fulfillment Order Management 4.0.2 HF-12 to TIBCO® Order Management 6.0.0, run the following command:

$ tibemsadmin -server tcp://localhost:7222 -user admin -script $OM_HOME/ems/UpgradeEMSChannel_FOM4.0.2HF12_to_6.0.0.txt

To upgrade the EMS channel from TIBCO Order Management - Long Running 5.0.0 HF-5 to TIBCO® Order Management 6.0.0, run the following command:

$ tibemsadmin -server tcp://localhost:7222 -user admin -script $OM_HOME/ems/UpgradeEMSChannel_5.0.0-LR-HF5_to_6.0.0.txt

To upgrade the EMS channel from TIBCO® Order Management 5.1.0 HF-7 to TIBCO® Order Management 6.0.0, run the following command:

$ tibemsadmin -server tcp://localhost:7222 -user admin -script $OM_HOME/ems/UpgradeEMSChannel_5.1.0-HF7_to_6.0.0-HF0.txt

Merging Configurations

The following applicationIds are renamed to make them more readable:

  • Data service is renamed to data-service

  • omsui is renamed to oms-ui

These applicationIds must now be updated in the back-end store as well. To update the applicationIds for the existing configuration, complete the following steps:

    Procedure
  1. Use the GET APIs to download the configuration files and application properties for the mentioned APIs.

  2. Use delete APIs to delete the existing applications (data service and omsui)

  3. Upload the downloaded configuration files again and upload the latest application properties from the $OM_HOME/seed-data/app-properties directory and reconfigure as per the existing values for the new applicationIds.

  4. Configure all other applications again as per your requirements.

Merge the previous configurations with the current configurations. For more details, see Task 9: Uploading Metadata file, App Properties, Config Files through Configurator UI and Task 10: Configuring minimum requirements through Configurator UI

  • Change the defaultAckMode property value for the "common" configuration. Here possible values are REST and MESSAGING.

  • Change the authorizationServiceTokenEndPoint property value from http://localhost:9091/oauth/token to http://localhost:9091 for "common" configuration.

  • Change the migrationURL property value for the Orchestrator configuration > 'Migration Service Configurations' category.

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.0 HF-5/Fulfillment Order Management 4.0.2 HF-12 and Order Management 5.1.0 HF-7, the order of the latter gets replaced during migration.

  • Audit trail logs for final state orders are migrated, but audit trail logs for in-progress orders are not seen after migration. If you do some action on Order Management 6.0.0 orders, then only the log is generated and seen on the UI.

  • Catalog is not migrated. You need to reload models on Order Management 6.0.0

FOM 4.0.2 HF-12 or OM-LR 5.0.0 HF-5 to OM 6.0.0

Offline Migration

The service is called as offline migration, because before you start using the Orchestrator from Order Management 6.0, you need to complete the migration. This is an on-demand service. You can choose which orders to migrate and which one to not.

    Procedure
  1. Set the database properties from the source version in the oracle_migration_db or postgres_migration_db file under the $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0 folder.
  2. Run the db-setup.sh script from the $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0/postgreSQL or $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0/oracle directory.
    This script creates the MIGRATED_ORDERS table in the Order Management - Long Running 5.0.0 HF-5 or Fulfillment Order Management 4.0.2 HF-12 database, which is used to track the orders that are migrated.
  3. 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 source from where the migration is done.
    2. Select the Data Source Configuration for legacy Application category and provide the default tenant database property details of the source from where the migration is done.
    3. Select the Messaging Configuration category and provide the properties details of the source from where the migration is done.
      Note: The current EMS and the source version must be the same.
    4. Select the Archival Database Configurations for 6.0 Application category and provide properties details from the current database.
    5. Select the Order Data Source Configuration for 6.0 Application category and provide properties details from the current database.
    6. (Optional) Select the Migration Functional Configuration category and set the value of the com.tibco.offlineMigration.migrateOrderInFinalState flag as true to migrate the final state (CANCELLED, COMPLETE) orders.
  4. 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).

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

  6. To access the Swagger REST API, enter the following endpoint in a browser: http://localhost:9100/V1/migration/order.

  7. On the /migration/order endpoint, run the request to migrate orders. You can enter various criteria such as orderID, orderRef, or dateRange.

    Sample:

    {
      "orderID": "string",
      "orderRef": "string",
      "dateRange":
    
    {     "startDate": "2023-01-24T18:31:57.274Z",     "endDate": "2023-01-24T18:31:57.274Z"   }
    ,
      "status": [
        "string"
      ],
      "headerUdfs": [
       
    
    {       "name": "string",       "value": "string"     }
      ],
      "orderLineUdfs": [
       
    
    {       "name": "string",       "value": "string"     }
      ]
    }
  8. Start the other services. See Task 11: Starting or Restarting the Services

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 with Order Status as Blocked.

Online Migration

The service is called as online migration, because the source version in-flight orders can be processed in 6.0. 0 version directly. You have to stop the services for the migration procedure.

Online Migration is performance intensive as the in-flight orders are migrated and on each order submission, there is a call to the migration service. Also, irrespective of the order status, all the orders are migrated.

    Procedure
  1. Set the database properties from the source version in oracle_migration_db or postgres_migration_db file under the $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0 folder.
  2. Run the db-setup.sh script from the $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0/postgreSQL or $OM_HOME/db/dbscripts/migration_from_Legacy_To_6.0.0/oracle directory.
    This script creates the MIGRATED_ORDERS table in Order Management - Long Running 5.0.0 HF-5 or Fulfillment Order Management 4.0.2 HF-12 database, which is used to track the orders that are migrated.
  3. Set the migrationEnabled flag value as true from the configurator UI for the orchestrator application > 'Migration Service Configurations' category.
    Note: You can deploy this flag at run time. You do not have to restart the orchestrator.
  4. Click the actuator refresh endpoint /management/refresh from the Orchestrator service Swagger REST API.

Offline-Online Combined

Both the online and offline migration services have their own 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 some of the orders that stay pending for a long duration, offline migration is more useful.

OM 5.1.0 HF-7 to OM 6.0.0

For TIBCO® Order Management 5.1.0 HF-7 to TIBCO® Order Management 6.0.0 migration, only the database and EMS are upgraded and data seeding is done again.

Before you start the migration, stop all the OM 5.1.0 HF-7 running services.

    Procedure
  1. Navigate to the $OM_HOME/db/dbscripts/postgreSQL/<database-name>/bin or the $OM_HOME/db/dbscripts/oracle/<database-name> directory.

  2. Update the postgres_<service-name>_db.properties or oracle_<service-name>_db.properties for all the databases (except Orchestrator) with Order Management 5.1.0 HF-7 database details.
  3. Run the upgrade_5.1.0hf7_to_6.0_db-setup.sh script (for all services except Orchestrator).

  4. Navigate to the $OM_HOME/ems directory and run the UpgradeEMSChannel_5.1.0-HF7_to_6.0.0-HF0.txt script.

  5. Start the Authorization, Configurator, and Configurator UI services.

  6. Merge the configurations. See Merging Configurations.

OM 6.0.0 to OM 6.0.0 HF-1

For TIBCO® Order Management 6.0.0 to TIBCO® Order Management 6.0.0 HF-1 migration, only the database, and EMS are upgraded.

Before you start the migration, stop all the OM 6.0.0 running services.

Note:

After upgrading the version to 6.0.0 HF-1:

  • You need to create tenants and users as the previous users are no longer available. See the "Registering a Tenant" section in the TIBCO® Order Management Administration for more details.

  • The notification table from the order database is dropped and created again. So older notifications are no longer available.

  • If the identityProviderType is POSTGRES or ORACLE, then create a user database for it from ${OM_HOME}/db/dbscripts/postgreSQL/user/bin or ${OM_HOME}/db/dbscripts/oracle/user directory respectively.

    Procedure
  1. Navigate to the $OM_HOME/db/dbscripts/postgreSQL/<database-name>/bin or the $OM_HOME/db/dbscripts/oracle/<database-name> directory.

  2. Update the postgres_<service-name>_db.properties or oracle_<service-name>_db.properties for admin and order database with Order Management 6.0.0 database details.
  3. Run the upgrade_6.0.0_to_6.0.0hf1_db_setup.sh script for the mentioned databases and run the ./seed_common_authConfig_db_setup.sh script for the admin database.

  4. A new database user is introduced from this release. Update the $OM_HOME/db/dbscripts/postgreSQL/user/bin/postgres_user_db.properties or $OM_HOME/db/dbscripts/oracle/user/oracle_user_db.properties file.

  5. Run the db-setup.sh file for the user database.

  6. Run the orch-db-migration utility from the $OM_HOME/samples/orch-db-migration/standalone/bin directory. See the README.md file present in the $OM_HOME/samples/orch-db-migration/standalone directory.

  7. Navigate to the $OM_HOME/ems directory and run the UpgradeEMSChannel_6.0.0_to_6.0.0-HF1.txt script.