11 OSM Pre-Production Testing and Tuning

About Work Managers, Work Manager Constraints, and the JDBC Connection Pool

OSM uses work managers to prioritize and control work. You can tune work managers using work manager constraints, which is an effective way to prevent overloading the managed servers in the OSM WebLogic Server cluster. The work manager constraints limit the number of threads available to OSM work managers.

The OSM installer creates only one maximum thread constraint shared by all OSM work managers. While this performs well in a development environment, this configuration is not the best approach in a production environment. For example, in a production environment under high load, this configuration can cause all available threads to alternate between the automation work manager (osmAutomationWorkManager) and the JMS web service work manager (osmWsJmsWorkManager), impacting core order processing capabilities.

To better control the flow of orders, Oracle recommends that you set the following values for thread constraints:

• osmJmsApiMaxThreadConstraint for the osmWsJmsWorkManager work manager. The osmJmsApiMaxThreadConstraint should be 12.5% of the total number of threads when you initially begin the tuning process.

• osmHttpApiMaxThreadConstraint for the osmWsHttpWorkManager and osmXmlWorkManager work manager. The osmHttpApiMaxThreadConstraint should be 12.5% of the total number of threads when you initially begin the tuning process.

• osmGuiMaxThreadConstraint for the osmTaskClientWorkManager, osmOmClientWorkManager work managers. The osmGuiMaxThreadConstraint should be 25% of the total number of threads when you initially begin the tuning process.

• osmAutomationMaxThreadConstraint for the osmAutomationWorkManager work manager. The osmAutomationMaxThreadConstraint should be 50% of the total number of threads when you initially begin the tuning process.

After you have completed the tuning process, you will set these constraints to values that enable maximum performance while ensuring that the server does not get overloaded or encounter alternating thread issues.

You must also ensure that every OSM thread always has access to a database connection. Oracle recommends that you set the maximum number of work manager threads to 80% of the database connection pool. One approach to this configuration is to first determine the total number of threads needed by adding all the maximum work manager constraints together, and then set the database connection pool to 125% of this number.

About the JBoss and Coherence Order Cache

OSM uses JBoss and Coherence order caches that determine how many orders can stay in active memory and for how long before being removed from the cache. Tuning the JBoss and Coherence order caches also prevents the managed servers in the OSM WebLogic Server cluster from being overloaded.

Synchronizing Time Across Servers

It is important that you synchronize the date and time across all machines that are involved in testing, including client test drivers. In production environments, Oracle recommends that you do this using Network Time Protocol (NTP) rather than manual synchronization. Synchronization is important in capturing accurate run-time statistics.

Determining Database Size

The size of the database (amount of memory, number of CPUs, and storage capacity) has an impact on performance. Oracle recommends that you run tests using the same size database that is planned for the production environment. You can do this by seeding the database with data, migrating data, or running a representative set of sample orders. Initial testing against an empty database only highlight the most serious problems. With an empty schema, database performance problems that relate to gathering optimizer statistics that are inaccurate will not become apparent until after the OSM system enters production.

This chapter provides instructions for populating the database with orders, warming up the system, and running database optimizer statistics so that the performance test generates accurate results.

Setting Up Emulators

If the entire system is not available for testing, you can set up emulators to simulate external requests and responses. For example, if you need to test OSM performance before the billing or inventory system is ready, you can use emulators.

If you are using the Order-to-Activate cartridges, OSM provides an Oracle Application Integration Architecture (Oracle AIA) Emulator, which you can use to emulate order responses. If possible, run emulators on separate hardware from the OSM server so they do not consume OSM resources during performance testing. For more information about setting up and using Oracle AIA emulators, see OSM Cartridge Guide for Oracle Application Integration Architecture.

Setting Up a Test Client for Load Generation

You can use a test client to submit the orders for performance testing. The test client can be a custom application or any third-party tool, such as JMeter, LoadUI, or SoapUI. The examples used in this chapter are from a SoapUI project.

Keep the following in mind when setting up a test client:

• Ensure the test client does not impact OSM hardware resources. It is best to run test clients on different hardware from the hardware where OSM is deployed.

• Ensure the number of test client threads is configurable and supported in the test client machine. This is essential for load and scalability testing because the number of concurrent users that the system can support is based on the number of test client threads. If high loading is required, you might need to use multiple test client machines to generate a sufficiently high load.

• Ensure the test client can provide vital statistics on performance data, such as average, maximum, standard deviation, and 90th percentile performance numbers.

• Ensure the test client can complete long running tests with a steady load.

Setting the Order Volatility Level

Before you warm up your system, you can specify whether you have low, medium, or high volatility orders for a specific group of database tables. Order with high volatility last for only a few second. Orders with low volatility can last for hours or even days. Orders that are a mix of high or low volatility can be classified as medium volatility. You must specify the order volatility level for these tables because the volatility level is dependent on the solution. For more information about statistics, see OSM System Administrator's Guide.

Log in to the OSM core schema and run the following commands to set the order volatility level:

execute om_db_stats_pkg.set_table_volatility('OM_ORDER_FLOW',om_const_pkg.v_volatility_volatility_level);
execute om_db_stats_pkg.set_table_volatility('OM_AUTOMATION_CTX',om_const_pkg.v_volatility_volatility_level);
execute om_db_stats_pkg.set_table_volatility('OM_AUTOMATION_CORRELATION',om_const_pkg.v_volatility_volatility_level);
execute om_db_stats_pkg.set_table_volatility('OM_ORDER_POS_INPUT',om_const_pkg.v_volatility_volatility_level);
execute om_db_stats_pkg.set_table_volatility('OM_UNDO_BRANCH_ROOT',om_const_pkg.v_volatility_volatility_level);
execute om_db_stats_pkg.set_table_volatility('OM_ORCH_DEPENDENCY_PENDING',om_const_pkg.v_volatility_volatility_level);

where volatility_level is low, medium, or high.

Warming Up the OSM System

Before an OSM performance test, you must start and run the WebLogic servers and the database so that all Java classes compile and the cache of the database populates with data. Typically, running the system for 5 to 10 minutes at 30 percent of its maximum order intake is enough, at which point the WebLogic server CPU usage and database input/output have stabilized.

After the initial warm-up period, you must run orders again at a higher rate to gather database statistics about low, medium, and high volatility tables. Do not gather statistics unless you have properly warmed up the system or the statistics will not be representative.

While you are running the orders, you must also set various JBoss and Coherence order cache values in preparation for the performance test.

For example, to run a warm up session with SoapUI, do the following:

1. Download and install SoapUI.

2. Create a SoapUI project.

3. Within the project, create a test suite.

4. Create a test step for CreateOrderBySpecification using a single order.

5. Open the order.

6. Click on the address bar and select Add new endpoint.

   The Add new endpoint screen is displayed.

7. Enter the following:

   http://hostname:port/OrderManagement/wsapi
   

   where hostname is the managed server host name or IP address and port is the port number of the managed server.

8. Submit the order to verify connectivity with the OSM managed server.

9. Create a load test with the representative set of orders.

10. Open the load test.

11. In the Limit field enter a number. For example 600. This value in seconds causes the load test to run for 10 minutes which is enough of the initial warm up time to enable the Java classes to compile.

12. In the Threads field, enter 4.

13. In the Delay field, enter a number. For example 15000. This value represents a 15000 millisecond delay interval (2.5 seconds) in which SoapUI submits the orders. The higher the value, the longer the delay, and the fewer orders are submitted. The lower the value, the shorter the delay, and more orders are submitted.

14. Open a terminal and run the following command:

    ps -ef | grep managed_server
    

    where managed_server is the name of the managed server you are tuning. The output specifies the current user name running the managed server and the first set of numbers specifies the process ID (PID) number of the managed server.

15. Run Java_home/bin/jconsole (where Java_home is the JDK root directory) to run the JConsole application for monitoring

    The New Connection screen is displayed.

16. Select the PID that corresponds to the one from the results in step 14.

17. Click Connect.

18. Click Insecure.

19. Click the Memory tab.

20. From the Chart list, select Memory Pool "PS Old Gen".

21. Monitor the life data size (LDS) which is the number of live objects that remain after a garbage collection. Ensure that the LDS is no more than 30% of the maximum old generation during the warm up process. If the order rate causes the LDS to increase above 30%, then the managed server is processing too many orders. Increase the Delay field amount on the SoapUI Load Test screen until you see the live objects after garbage collection return to 30%.

    For example, Figure 11-1 shows a small 2.5 GB managed server running with more than 30% live objects after garbage collection.

    Figure 11-1 JConsole LDS Size Above 30%

    
    

22. After the initial performance test to compile the Java classes completes, set the Limit value to a higher number. For example 1800 for a 30 minute performance test for gathering database statistics.

    Note:

    The duration you set depends on the OSM system being tested. Some systems may require longer than 30 minutes.

23. Start the performance test for gathering low volatility statistics and determining order cache eviction time.

24. Log in to the order management schema.

25. Enable incremental statistics on low volatility orders.

    execute om_db_stats_pkg.set_table_prefs_incremental(a_incremental => true,a_volatility => om_const_pkg.v_volatility_low);
    

26. After the performance test has completed, gather statistics on the low volatility orders. Because the database is no longer processing orders, you can use all available threads (default behavior) to gather statistics.

    execute om_db_stats_pkg.gather_order_stats(a_force => true,a_volatility => om_const_pkg.v_volatility_low); 
    

27. Use the OSM Task web client and verify the average time it takes for orders to complete.

    To verify the average time it take for order to complete, do the following:

    1. Log in to the OSM Task web client.

    2. Click Reporting.

    3. Click Completed Order Statistics.

    4. In the From field, enter the starting time and date for the current performance test.

    5. In the To field, enter the current time and date for the performance test.

    6. Click Find.

    7. Compare the average time it take for orders to complete from the Avg Time column with the longest time it take for orders to complete from the Highest Time column. You can use these values to determine how long orders should stay in the cache before being evicted. For example, if orders, on average, take three minutes to complete and it took five minutes for the longest, then a four minute cache eviction timeout for inactivity would be reasonable. Or, if most orders take 30 minutes to complete and the longest took 50 minutes to complete, then a forty minute timeout for inactivity would be enough. The inactivity timeout should capture 80% of your order volume.

28. Using a text editor, open the domain_home/oms-config.xml file.

29. Add the following text to the bottom of the file before the final </oms-configuration> tag to configure the JBoss cache:

    <oms-parameter>
        <oms-parameter-name>ClosedOrderCacheMaxEntries</oms-parameter-name>
        <oms-parameter-value>60</oms-parameter-value>
    </oms-parameter>
    <oms-parameter>
        <oms-parameter-name>ClosedOrderCacheTimeout</oms-parameter-name>
        <oms-parameter-value>60</oms-parameter-value>
    </oms-parameter>
    <oms-parameter>
        <oms-parameter-name>OrderCacheMaxEntries</oms-parameter-name>
        <oms-parameter-value>order_max</oms-parameter-value>  
    </oms-parameter>
    <oms-parameter>
        <oms-parameter-name>OrderCacheInactivityTimeout</oms-parameter-name>
        <oms-parameter-value>inactivity_timeout</oms-parameter-value>
    </oms-parameter>
    

    where

    • order_max is the maximum number of orders that can be in the managed server's JBoss cache. Set this value to a high number, such as 2000 for the purposes of performance tuning procedure. You will change this number to a lower setting after completing the performance tuning procedure.

    • inactivity_timeout is the value you determined in step 27 in seconds. This timeout evicts an order from the JBoss cache.

30. Save and close the file.

31. Using a text editor, open the osm-coherence-cache-config.xml file. See "Configuring and Monitoring Coherence Threads" for more information about locating and externalizing the osm-coherence-cache-config.xml file.

32. Search on osm-local-large-object-expiry:

    <scheme-name>osm-local-large-object-expiry</scheme-name>
         <eviction-policy>LRU</eviction-policy>
         <high-units>order_max</high-units>
       <low-units>0</low-units>
         <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>inactivity_timeout</expiry-delay>
            <flush-delay>1000ms</flush-delay>
      </local-scheme>
    

    where

    • order_max is the maximum number of orders that can be in the managed server's Coherence cache. Set this value to a high number, such as 2000 for the purposes of performance tuning procedure. You will change this number to a lower setting after completing the performance tuning procedure.

    • inactivity_timeout is the value you determined in step 27 in seconds. This timeout evicts an order from the Coherence cache.

33. Save and close the file.

34. Restart all servers.

35. In the SoapUI load test screen, change the Delay field to a smaller number, such as 12000 which is two seconds, and run a second 30 minute load test.

36. Start the performance test for gathering medium and high volatility statistics.

37. Monitor the life LDS and ensure that the LDS is no more than 50% of the maximum old generation. If the order rate causes the LDS to increase above 50%, increase the Delay field amount on the SoapUI Load Test screen.

38. Log in to the order management schema.

39. Enable incremental statistics on medium and high volatility orders.

    execute om_db_stats_pkg.set_table_prefs_incremental(a_incremental => true,a_volatility => om_const_pkg.v_volatility_medium);
    execute om_db_stats_pkg.set_table_prefs_incremental(a_incremental => true,a_volatility => om_const_pkg.v_volatility_high);
    

40. During the performance test, gather statistics on the medium and high volatility orders. The following statements also reduce the number of threads used for gathering statistics to two so that order processing does not suffer a performance impact.

    execute DBMS_STATS.SET_SCHEMA_PREFS(user, 'DEGREE', 2); 
    execute om_db_stats_pkg.gather_order_stats(a_force => true,a_volatility => om_const_pkg.v_volatility_high); 
    execute DBMS_STATS.SET_SCHEMA_PREFS(user, 'DEGREE', 'DBMS_STATS.AUTO_DEGREE');
    
    execute DBMS_STATS.SET_SCHEMA_PREFS(user, 'DEGREE', 2); 
    execute om_db_stats_pkg.gather_order_stats(a_force => true,a_volatility => om_const_pkg.v_volatility_medium); 
    execute DBMS_STATS.SET_SCHEMA_PREFS(user, 'DEGREE', 'DBMS_STATS.AUTO_DEGREE');
    

Determining the Sustainable Order Rate for a Managed Server

The following procedure should be done after completing warm up procedures.

1. Log on to the Oracle database as sys or the equivalent (traditional database or the pluggable database) and create an Oracle database automatic workload repository (AWR) snapshot.

2. Open the SoapUI load test.

3. In the Limit field enter a number. For example 3600. This value is in seconds and causes the load test to run for 60 minutes, which is enough for the performance test although in some cases a longer period is required.

4. In the Threads field, enter 4.

5. In the Delay field, enter a number. For example 15000. This value represents a 15000 millisecond delay interval (2.5 seconds) between order submissions. The higher the value, the longer delay, and the less orders are submitted. The lower the value, the shorter the delay, and more orders are submitted.

6. Start the performance test.

7. As you are running the performance test, run JConsole.

8. Monitor the LDS and ensure that the level is stable at around 50% of the maximum old generation. If the order injection rate causes the LDS to increase above 50% for an extended time and if the LDS continues to increase so that garbage collection becomes more and more frequent, then decrease the number of orders you submit by increasing the Delay field amount on the SoapUI Load Test screen. For example, you might move from a 2.5 second delay to a 3 second delay.

   Figure 11-2 shows garbage collection with a steadily increasing frequency and LDS size. If the order injection rate were to remain at the current level, the managed server would eventually crash.

   The inverse scenario is also possible where the LDS size is lower than 50% and the frequency of garbage collection is much longer. In this case, you must increase the order injection rate by decreasing the Delay field amount on the SoapUI Load Test screen.

   Figure 11-2 JConsole Garbage Collection Frequency and LDS Size

   
   

   Note:

   The frequency of garbage collection and the size of the LDS for a 32 GB managed server is much larger than is depicted in Figure 11-2. The maximum old generation in a 32 GB managed server is 17 GB and the target LDS is 50% of the old generation which is 8.5 GB. Depending on the size and complexity of your orders, garbage collection make take a long time to occur. For example, garbage collection may only occur once every half hour. If very long garbage collection intervals are occurring, then increase the length of the performance test to two or even three hours to get an accurate garbage collection sampling. See step 3 to increase the length of the performance test.

9. When the LDS level has stabilized during the performance test, verify the number of automation threads being used to support the current number of orders that the managed server is processing. This value will be used to set the work manager maximum thread constraint for automations.

   To verify the number of automation threads in use and set the automation work manager maximum constraint, do the following:

   1. Log in to the WebLogic Server Administration Console.

      The WebLogic Administration Console is displayed.

   2. In Domain Structure, expand Environment and then select Servers.

      The Summary of Servers page is displayed.

   3. Click the name of the WebLogic server that you are tuning.

      The configuration parameters for the server are displayed on a tabbed page.

   4. Click the Monitoring tab.

   5. Click the Threads subtab.

   6. Above the Self-Tuning Thread Pool Threads table, click Customize this table.

   7. In the Filter by Column list, select Work Manager.

   8. In the Criteria field, enter osmAutomationWorkManager.

   9. Click Apply.

   10. Refresh the screen every minute over 30 minutes to determine the highest number of active osmAutomationWorkManager threads you see after a refresh during that time.

       Figure 11-3 shows the beginning of a table that lists 60 active automation threads.

       Note:

       It is possible that there may be no active threads after refreshing. This does not indicate a problem unless the result occurs consistently.

       Figure 11-3 Automation Threads

       
       

10. Determine the maximum number of orders that can be in the JBoss and Coherence cache:

    1. Open a terminal on the machine running the manager server that you are tuning.

    2. In a text editor, open domain_home/servers/managed_server/logs/managed_server.out (where managed server is the name of the managed server you are tuning).

    3. Search the log file for cache information using the # Orders Information text. Search through all instances and find the highest instance of the Orchestration Cache or the Order Cache value (whichever is greater of the two, although they are typically identical).

       This example, after searching through 30 cache information instances, the following cache information instance shows the highest set of cache values:

       Cache                  % Full # Orders Information
       ---------------------- ------ -------- -----------
       Closed Order Cache        12%   6/50
       Historical Order Cache     8%   80/1000
       Orchestration Cache       40%   400/1000
       Order Cache               40%   401/1000
       Redo Order Cache           0%   0/1000
       
       

       You would select the Order Cache number in this example because it is higher than the Orchestration Cache number.

11. After you finish the test, log on to the Oracle database again and create a second AWR snapshot.

12. Generate a report using both AWR snapshots.

13. Ask a database administrator (DBA) to analyze the AWR report to determine whether the database is performing as expected. DBAs are trained to detect database performance issues such as an undersized database or suboptimal SQL statement execution plans.

Tuning Work Manager Constraints and the Maximum Connection Pool Capacity

To set work manager constraints and the maximum connection pool capacity for OSM JDBC data sources, do the following:

1. Log in to the WebLogic Server Administration Console.

2. In Domain Structure, expand Environment, and then select Work Managers.

   The Summary of Work Managers page is displayed.

3. Click Lock & Edit.

4. Select the osmAutomationMaxThreadConstraint.

   The Configuration tab appears.

5. In the Count field, enter the number of automation threads you observed in step 9 of the "Determining the Sustainable Order Rate for a Managed Server" procedure.

   The example in Figure 11-3 of step 9 showed 60 automations active.

6. Click Save.

7. In Domain Structure, expand Environment, and then select Work Managers.

   The Summary of Work Managers page is displayed.

8. Select the osmGuiMaxThreadConstraint.

   The Configuration tab appears.

9. In the Count field, enter a number. This value is typically half of the osmAutomationMaxThreadConstraint count although if you have a solution that makes extensive use of manual tasks, you may need to raise this value.

   For example, if the osmAutomationMaxThreadConstraint was 60 then the osmGuiMaxThreadConstraint would be 30. However, if the OSM client users begin to experience long delays before they can gain access to an OSM client session, then you may want to raise this value. You should include OSM client users in you performance test to ensure that the ratio of threads allocated to osmGuiMaxThreadConstraint and osmAutomationMaxThreadConstraint is properly balanced.

10. Click Save.

11. In Domain Structure, expand Environment, and then select Work Managers.

    The Summary of Work Managers page is displayed.

12. Select the osmJmsApiMaxThreadConstraint.

    The Configuration tab appears.

13. In the Count field, enter a number. A typical starting value is between 4 to 6 which is enough in most cases. If the overall heath of the managed server and the database are good, but the web service JMS queue is accumulating messages, then this value could be increased. Increase the value incrementally, and run additional performance tests to ensure that the overall health of the managed server and database continues to be good.

14. Click Save.

15. In Domain Structure, expand Environment, and then select Work Managers.

    The Summary of Work Managers page is displayed.

16. Select the osmHttpApiMaxThreadConstraint.

    The Configuration tab appears.

17. In the Count field, enter a number. A typical starting value is between 4 to 6 which is enough in most cases. If the overall heath of the managed server and the database are good then this value could be increased. Increase the value incrementally, and run additional performance tests to ensure that the overall health of the managed server and database continues to be good.

18. Click Save.

19. Add the all the maximum constraints you have configured and divide the total by 0.80 (80%) to determine the maximum connection pool size. For example, if you had the following constraint values:

    • osmAutomationMaxThreadConstraint = 60

    • osmGuiMaxThreadConstraint = 30

    • osmJmsApiMaxThreadConstraint = 5

    • osmHttpApiMaxThreadConstraint = 5

    which results in 100 / 0.80 which equals = 125 maximum connection pool size.

20. Log in to the WebLogic Server Administration Console.

    The WebLogic Administration Console is displayed.

21. In Domain Structure, expand Services, and then select Data Sources.

    The Summary of JDBC Data Sources screen is displayed.

22. Select an OSM JDBC data source. The OSM JDBC data source are as follows:

    osm_pool_sid_group_y
    

    where sid is the Oracle RAC database instance system identifier and y is the group letter.

    The Configuration tab is displayed

23. Click the Connection Pools tab.

24. In the Maximum Capacity field, enter the value you calculated in step 19.

25. Click Save.

26. Repeat steps 21 to 25 for all other OSM JDB connections.

27. Click Activate Changes.

Tuning the JBoss and Coherence Maximum Order Cache

To set the maximum number of orders in the JBoss and Coherence cache for managed servers, do the following:

1. Using a text editor, open the domain_home/oms-config.xml file.

2. Change the JBoss OrderCacheMaxEntries value:

   <oms-parameter>
       <oms-parameter-name>OrderCacheMaxEntries</oms-parameter-name>
       <oms-parameter-value>order_max</oms-parameter-value>  
   </oms-parameter>
   

   where order_max is the maximum number of orders that can be in the managed server's JBoss cache. Set this value to the number orders in the cache that you observed in step 10 of the "Determining the Sustainable Order Rate for a Managed Server" procedure.

3. Save and close the file.

4. Using a text editor, open the osm-coherence-cache-config.xml file. See "Configuring and Monitoring Coherence Threads" for more information about locating and externalizing the osm-coherence-cache-config.xml file.

5. Search on osm-local-large-object-expiry:

   <scheme-name>osm-local-large-object-expiry</scheme-name>
        <eviction-policy>LRU</eviction-policy>
        <high-units>order_max</high-units>
   

   where order_max is the maximum number of orders that can be in the managed server's Coherence cache. Set this value to the number orders in the cache that you observed in step 10 of the "Determining the Sustainable Order Rate for a Managed Server" procedure.

6. Save and close the file.

Sizing the Redo Log Files

Using the AWR log files generated in the "Determining the Sustainable Order Rate for a Managed Server" section, check the log switches (derived) statistics. Log switching should occur at a frequency no less than 20 minutes apart. If the frequency of log switching is less than 20 minutes apart, then the redo log files are undersized. Increase the log file size, or number of redo groups, or both.

Checkpoint frequency is affected by several factors, including log file size and the FAST_START_MTTR_TARGET initialization parameter. If you set this parameter to limit the instance recovery time, Oracle Database automatically tries to checkpoint as frequently as necessary. The optimal size can be obtained by querying the OPTIMAL_LOGFILE_SIZE column from the V$INSTANCE_RECOVERY view. If FAST_START_MTTR_TARGET is not set, OPTIMAL_LOGFILE_SIZE is not set either.

For more information about sizing redo log files, see Oracle Database Performance Tuning Guide.

If the above change does not reduce checkpoint frequency, use the renice command to set the Log Writer Process (LGWR) to run at higher priority or run LGWR in the redo thread (RT) class by adding LGWR to the parameter: _high_priority_processes='VKTM|LGWR". Only change _high_priority_processes in consultation with database support. For example, more processes may need to be added, such as PMON. And if the database is an Oracle RAC database, LMS should be added to this parameter. Test this change thoroughly.

Finally, if all other methods fail to reduce checkpoint frequency, set the _log_parallelism_max hidden parameter after consultation with database support.

Enabling the OM_ORDER_NODE_ANCESTRY Table

When the OM_ORDER_NODE_ANCESTRY table is enabled, OSM populates the OM_ORDER_NODE_ANCESTRY table with data and uses queries on this table to support UI worklist and order searches. Running OSM in this mode is effective for new order id blocks. A new block is allocated when the current partition where new orders are created (known as the active partition) is exhausted.

Order ids are stored in the OM_ORDER_ID_BLOCK table. In this table, a column called ANCESTRY_POPULATED_UP_TO indicates the last order id in the block of order ids that has data in the OM_ORDER_NODE_ANCESTRY table.

An active order id block can be split logically, as in the following example:

• An order id block contains order ids from 0 to 100000. The order id block is NOT split yet and all order ids in this block contain ancestry data.

• An order id block is split. Orders ids between order id 0 and 2000 have ancestry data. Orders between order id 2001 and 100000 do not have ancestry data.

A block of order ids is active if it is the latest block for the current database instance (DBINSTANCE). The previous blocks for the database instance are inactive blocks.

When users retrieve worklist tasks or search for orders, OSM uses the data in order id blocks to determine if queries are run against the OM_ORDER_NODE_ANCESTRY table (old queries) or the OM_ORDER_INSTANCE table (new queries).

You might need to switch several times between running OSM with the OM_ORDER_NODE_ANCESTRY table enabled and disabled. The following example scenarios illustrate circumstances that might necessitate switching between the two modes.

Scenario 1: Introducing multi-instance subprocess entities (enable, disable, enable)

1. You have upgraded OSM to a later version that includes this functionality. OSM continues to run with the OM_ORDER_NODE_ANCESTRY table enabled.

2. Because of large volumes of orders, you determine that OSM cartridges do not use multi-instance subprocesses and decide to disable the OM_ORDER_NODE_ANCESTRY table.

3. Some time later, you introduce multi-instance sub-process entities (for example, OSM needs to run a sub-process for each of the multiple addresses a customer has) by redeploying existing, or deploying new, cartridges.

4. You then determine that the worklist demonstrates performance degradation and decide to re-enable the OM_ORDER_NODE_ANCESTRY table.

Scenario 2: Eliminating multi-instance subprocess entities (disable, enable, disable)

1. You install the latest release of OSM, which includes this functionality. The OM_ORDER_NODE_ANCESTRY table is disabled.

2. You deploy a cartridge that uses multi-instance subprocesses, and leave the table disabled because performance test results are satisfactory.

3. You then determine that the worklist demonstrates performance degradation and decide to enable the OM_ORDER_NODE_ANCESTRY table.

4. Some time later, you redeploy updated cartridges so that all multi-instance subprocesses are eliminated. You then disable the OM_ORDER_NODE_ANCESTRY table.

You can run this procedure when OSM is online or offline.

To enable the OM_ORDER_NODE_ANCESTRY table:

1. Log in to SQL*Plus as the OSM core schema user.

2. Run the following command:

   begin 
                   om_order_node_ancestry_pkg.enable_ancestry_table; 
   end;
   

Disabling the OM_ORDER_NODE_ANCESTRY Table

Running OSM with the OM_ORDER_NODE_ANCESTRY table disabled is suitable if you are deploying cartridges that do not include multi-instance subprocesses. When you run OSM with the table disabled, the OM_ORDER_NODE_ANCESTRY table is not populated and hierarchical queries (for cartridges with multi-instance subprocesses) that are run using UI worklist or search functionality return ancestry data from the OM_ORDER_INSTANCE table.

You must disable the OM_ORDER_NODE_ANCESTRY table when OSM is offline because the procedure uses the last order id to split the block of order ids into two parts: populated and non-populated. For example, if the current order id is 100 and the last order id in the active block is 10000:

• [1...100...10000] is logically split into:

  • [1...100]: order ids with populated ancestry

  • [101...10000]: order ids with non-populated ancestry

To disable the OM_ORDER_NODE_ANCESTRY table:

1. Log in to SQL*Plus as the OSM core schema user.

2. Take the OSM server offline. For more information about stopping OSM, see OSM System Administrator's Guide.

3. Run the following command:

   begin 
           om_order_node_ancestry_pkg.disable_ancestry_table; 
   end;
   

   Note:

   You can run the disable OM_ORDER_NODE_ANCESTRY table procedure only once on a single block of ids because the current block of ids can be split only once.