Migrating the existing order data to Order Service

Sterling™ Order Management System Software provides indexing and search capabilities of transactional data through Order Search, a component of Order Service.

Sterling Order Management System Software provides a built-in integration for the ‘Order’ entity, and an outline of an order is saved in Order Search whenever it is created or modified in Sterling Order Management System Software. This brings the latest state of order to Order Search to search for orders without depending on Sterling Order Management System Software and Order Search becomes the single source of visibility for all the orders that are fulfilled through Sterling Order Management System Software.

Sterling Order Management System Software also supports archiving historical orders to Archive Service, another component of the Order Service feature. The built-in integration archives the historical order data to Archive Service and removes them from the Sterling Order Management System Software database after the order is successfully archived. You can access the historical data stored in Archive Service with the help of Archive Service APIs.

When you enable the built-in integration, orders created or updated in the Sterling Order Management System Software application server and agent/integration servers are saved and indexed in Order Search. The orders that are purged are staged for archival and at a later point of time when the archive agent runs the purged orders are archived to Archive Service and erased from Sterling Order Management System Software.

The orders which are created, modified, or purged from the time of enablement are processed automatically for indexing and staged for archive. But Sterling Order Management System Software contains orders that reached an end-state such as fulfilled, delivered, closed, waiting for purge, and so on. There could be orders that are on hold or waiting on some resolutions to proceed forward. Besides these, many orders would have reached history tables at the time of enabling the built-in integration with Order Service. So, for Order Search to become a single source of truth for orders that are fulfilled through Sterling Order Management System Software and to provide a search facility for orders to be archived soon, you must migrate these types of orders to Order Search. Also, the existing history orders must be staged for archive, and you should run the corresponding agent to archive eligible orders.

Sterling Order Management System Software provides synchronization agents to migrate all existing orders to Order Search and stage history orders for archive. To optimize the effort to save, index, and archive orders appropriately, you must adhere to the following steps.

Migration strategy

Complete the following actions in the following sequence:
  1. Assess and configure an outline template for Order entity through entity extensions in Sterling Order Management System Software. For more information, see Customizing the Search Index template.
  2. View the order outline template, choose the fields that you want to be searchable, sortable, and returnable, and so on based on your search and display requirements.
  3. Create a mapping schema for the order index in Order Search. For more information about mapping guidelines, see Creating an index mapping.
  4. Create an index with id=order by using the mapping by using admin APIs in Order Search. This creates an index for the current period. For more information about the createSearchIndex API, see Creating an index.
  5. Assess your history order volume. All the history orders are to be migrated to Order Search and typically distributed to more than one index instead of all orders in one index. So, locally group the history orders based on your volume. For example, one group for orders older than 5 years, another group for 3 to 4 years age, one for last to last year, and one group for last year orders.
  6. Create one order index for each of these logical group. Use the cloneSearchIndex API on Order Search for this. For more information about the cloneSearchIndex API, see Cloning an index.
  7. Configure the agent criteria. For more information about the agents, see Business process time-triggered transactions.
    1. Create an agent criteria for OSI_HISTORY_MASS_SYNC agent for each of these groups with the corresponding index name and the year duration. Ensure that none of these criteria are configured for auto-triggering and no overlapping of duration.
    2. Configure the agent criteria for SSI_DELAYED_SYNC. This criteria must be auto-triggered in short intervals.
    3. Configure the agent criteria for SSI_MASS_SYNC. Use ‘unindexed’ mode for migration purpose. Do not set for auto-triggering.
    4. Configure the agent criteria for OSI_ORDER_ARCHIVE.
  8. Trigger all the order purge agents across document types in Sterling Order Management System Software.
  9. After order purge, stop all agent servers where the order purge agent is running.
  10. Start Order Service in migration mode. That is set ORDERSERVICE_USE_INDEX_NAME_IN_REQUEST=true and deploy Order Service.
  11. Enable the built-in integration with Order Service. For more information, see Enabling Sterling Order Management System Software to connect to Order Service.
  12. Start the agent server where OSI_HISTORY_MASS_SYNC agent is associated with.
  13. Trigger the OSI_HISTORY_MASS_SYNC agent one by one for each criteria.
  14. After completion, stop the agent server where the OSI_HISTORY_MASS_SYNC agent is running.
  15. The history orders are soon to be archived and removed from Sterling Order Management System Software. In case of any index corruption on Elasticsearch index files, running the OSI_HISTORY_MASS_SYNC agent again cannot migrate all orders as they would have removed from Sterling Order Management System Software. Considering this, it is strongly recommend that you take a backup of the index data from Elasticsearch. To back up all the indices where order data is migrated, contact your Elasticsearch administrator.
  16. Stop Order Service and start in normal mode. That is remove or reset the ORDERSERVICE_USE_INDEX_NAME_IN_REQUEST property and redeploy Order Service.
  17. Start the server where the SSI_DELAYED_SYNC agent is associated with.
  18. Restart all Sterling Order Management System Software agents and integration servers that process order and rolling restart for application server. However, you must not start the order purge agents.
  19. Start the server where the SSI_MASS_SYNC agent is associated with and trigger the Mass Sync agent criteria one by one. All the unindexed non-history orders get migrated.
  20. After completion, stop the agent server where the SSI_MASS_SYNC agent is running.
  21. Log in to the System Management Administrator Console and mark order index as synchronized for all the enterprises for which you ran the SSI_MASS_SYNC agent.
  22. Start the agent servers where the order purge agent is associated with.
  23. Trigger the Order Archive agent as and when needed, or configure auto-trigger.

The non-history orders and all order modifications are sent to the index for the current period. Contact your Elasticsearch administrator periodically to monitor the index size. If the index file size is nearing to maximum file size as recommended by Elasticsearch, you must clone the current index to create an index. Despite that cloning the current index at regular time intervals based on your order volume is a good practice. It is recommended to follow this.

Backward Compatibility Reporting

Sterling Order Management System Software provides the ability to index Order and Shipment entities starting release 9.2.1 to optimize the order and shipment search operations in a sharded Sterling Order Management System Software instance. Starting release 9.4.0, the indexing capability is supported in a non-sharded Sterling Order Management System Software instance also so that you can build an Order Search solution with the order index. This implementation was using an Elasticsearch node client running within Sterling Order Management System Software JVMs. The client directly connects to an Elasticsearch master node and joins the Elasticsearch cluster. Starting release 10.0, this direct connection approach is unsupported and use of that is prohibited.

The built-in integration with Order Search is implemented newly in release 10.0 and some of the behaviors of erstwhile implementation is changed in the application-provided properties.

Here is the list of properties and their values to match the erstwhile implementation behavior. This is provided for backward compatibility reporting only and as mentioned the erstwhile search index integration is no longer supported since release 10.0.
  • yfs properties
    • yfs.ssi.disabled.entities=
    • yfs.ssi.entities.perform.custom.indexing=Order
    • yfs.ssi.delete.from.index.on.entity.purge=true
    • yfs.ssi.index.draft.orders=true
  • Elasticsearch property
    • yfs.elasticsearch.client.type=NodeClient