How to Be a Time Traveler Using pin_virtual_time

Have you ever wanted to travel through time? No need for a flux capacitor! Oracle BRM provides that exciting opportunity with the use of pin_virtual_time, which allows you to adjust the time of your BRM instance without changing your system time. Time traveling is not always appropriate or necessary, so let’s briefly go over some examples of when to use pin_virtual_time and how it should be used.

When to use pin_virtual_time

Pin_virtual_time should always be used in a testing environment. Common situations for using pin_virtual_time include but are not limited to:

• Testing if accounts are billed correctly by advancing the date to the next billing cycle, then running billing and generating an invoice. (This example is covered below in more detail.)
• Testing if a time-based discount takes effect correctly. For example, if you have a deal that includes 90 days of free email service, advance the date more than 90 days to see if the account starts being charged for the service.
• Testing if folds are working correctly. For example, if a product includes 10 free hours of Internet service per month, advance the date by a month or more to ensure that unused free hours do not carry over.

Proper use of pin_virtual_time

• Because the pin_virtual_time utility works only on a single environment, you should set up a test BRM system on just one server.
• Time should always be adjusted forward and never into the past.
• Only move time forward as far as necessary. For example, if you want to test a monthly billing charge, it is only necessary to move time forward by one month from the time of the account creation.
• To test custom client applications that are connected to the CM, you can use PCM_OP_GET_PIN_VIRTUAL_TIME to get the virtual time that is set by pin_virtual_time.

Words of caution

• Never use pin_virtual_time in a production environment.
• Time should not be adjusted forward farther than necessary.
• It’s possible to run pin_virtual_time on a system that is distributed across multiple computers, but you must carefully coordinate time changes on all the computers that are a part of the system. Therefore, it is more prudent to set up a test BRM system on a single computer or virtual machine.
• You may be wondering: “Can I travel back in time?” You can, but traveling back in time is NOT recommended for the following reasons:

1. Moving time backwards can cause severe data corruption.
2. Unless you’re rebuilding BRM from scratch, no situation requires traveling back in time.
3. Setting time back can result in events occurring out of order, which leads to unexpected complications with tests that are extremely difficult or impossible to resolve. Moving time backwards leads to data corruption and unexpected behavior in multiple areas of BRM, including pricing, which can taint your test environment.

Since the safest approach is to always know how your system behaves and why, you should always avoid moving pin_virtual_time into the past.

An example of how to use pin_virtual_time

In this example, we’ll time travel ahead one month and run billing to verify that all charges associated with a test plan appear on the test customer’s invoice. Pin_virtual_time can only be run from a directory with a valid pin.conf where the pointer is not commented out. Any application pin.conf file may contain the entry as well. To enable adjusting pin_virtual_time, uncomment the following line in the pin.conf file where pin_virtual_time is being run:

- - pin_virtual_time ${PIN_HOME}/lib/pin_virtual_time_file

The following out-of-the-box directories contain pin.conf files that can be updated to enable time travel:

• CM:  $PIN_HOME/sys/cm/
• CMMP:  $PIN_HOME/sys/cmmp/
• TEST: $PIN_HOME/sys/test/
• Billing Applications:  $PIN_HOME/apps/pin_billd/
• Invoicing:  $PIN_HOME/apps/pin_inv/

Always stop and restart BRM after updating the pin.conf files to allow changes to take effect. Once the configuration files have been updated, follow the steps below.

1. Set up a test scenario for the customer(s) and plan(s) to be verified with billing.
2. In your testing environment, enter the pin_virtual_time command to see the current virtual time displayed. We will be moving time forward by one month from this time.
3. To set pin_virtual_time to a specified time where the clock will continue to run, use mode 2 and set time forward one month from the current virtual time using this command:

pin_virtual_time -m 2 MMDDHHmmYYYY

a. You should generally always use mode 2 when setting time forward, but descriptions of all of the mode options are listed below for reference.

i. Mode 0 (normal mode) indicates that the system should use the operating system time with no adjustments.

ii. Mode 1 (freeze mode) indicates that the system should move forward to the entered time value, where time is frozen until pin_virtual_time is used again to change the time or mode. (Use this mode only when absolutely necessary, because BRM expects time to be moving.)

iii. Mode 2 (offset mode) sets the time forward to the entered time value and keeps the clock running forward.

4.  Run the pin_bill_day command to bill all customers. (It’s really that easy.) If you would prefer to only bill your test customer, see Alex Bramford’s blog on How to Bill One Account in BRM for Testing.

5.  Inspect the test account using your favorite tool. Any charges associated with the test customer’s plan should now appear.