22 Managing Orders

This chapter describes the Oracle Communications Billing and Revenue Management (BRM) Order Management framework and explains how to use its components to build custom order management systems.

Before you read this chapter, you should have a good understanding of BRM opcodes and storable classes. See "Understanding the PCM API and the PIN Library" and "Understanding Flists and Storable Classes".

If you plan to develop order management applications, you should also read "Adding New Client Applications" as well as the client applications document that covers the programming language you will use.

About the Order Management Framework

The Order Management framework enables you to write applications to manage orders and sub-orders in BRM or to connect an existing order management system to BRM. The Order Management framework is used by optional BRM products such as voucher manager to facilitate their order management features.

The Order Management framework is part of Inventory Manager, which is an optional, separately purchased feature.

In BRM, an order is a request for a physical or virtual object such as voucher cards or SIM cards. Both types of orders are represented in BRM as Storable objects. You use your Order Management framework to create orders for device inventory such as vouchers and SIM cards. The Order Management framework provides the /order storable class, which you can subclass to represent specific order types. Each object in /order or its subclasses represents an individual order.

Order management includes creating the order objects, controlling their life cycles and their attributes, processing orders, tracking their history, and removing orders when they are no longer needed. The framework provides storable classes, standard and policy events, and utilities for these purposes.

Order Management Tasks

The Order Management framework provides the following functionality:

• Creating Orders

• Processing Order Response Files

• Managing the Order Life Cycle

• Associating or Disassociating Orders with Master Orders

• Managing Order Attributes

• Deleting Orders

• Tracking Order History

• Managing the Order History Log

Creating Orders

Each order that you track in BRM is represented by an /order object. The way these objects are created depends on your business. You can create orders and sub-orders, and you can associate sub-orders with master orders.

While there are many scenarios for order creation, the actual process used is always the same: all order-creation applications call PCM_OP_ORDER_CREATE. This opcode creates BRM /order objects that use the order type, initial state, and attributes specified in the input flist. See "Creating /order Objects".

A policy opcode, PCM_OP_ORDER_POL_CREATE, enables you to customize the order creation process.

Because your business may need to manage several types of orders, the /order storable class can be subclassed to represent order types. Each order type is a group of orders that have similar characteristics. For example, Voucher Manager creates the /order/voucher order type.

You use Storable Class Editor, an application in Developer Center, to create new subclasses. See "Creating Custom Fields and Storable Classes".

The /order objects are brand aware. Their brand affiliation is determined by the brand affiliation of the login used to create the objects. See "Order Management and Brands" for more information.

Processing Order Response Files

After you create an order, you send it to the vendor or manufacturer and request an order response file. The manufacturer returns an order response file that lists the set of devices that are created. You then process this response file to store the data in the BRM database.

A policy opcode, PCM_OP_ORDER_POL_PROCESS, enables you to customize the /order object when you process an order.

Processing order response files includes creating devices such as vouchers in the database and updating the status of the requested order to either Received or Partially Received.

Managing the Order Life Cycle

Real-world orders pass through various stages. For example, an order can be new, received, or canceled. An order management system must keep track of these stages, or order states. In BRM, the order state is represented by the PIN_FLD_STATUS field in the /order object. The value of this field represents the current state of the order. The set of possible order states and state transitions defines the life cycle of an /order object.

Order life cycles are regulated by /config/order_state objects in the database. You define order states and state changes in a configuration file and load it into the database by using the load_pin_order_state utility. See "About Defining the Order Life Cycle" for more information.

Order management applications call PCM_OP_ORDER_UPDATE. This opcode is a wrapper opcode that calls one of the following opcodes to change order states, depending on the input flist provided for this opcode:

• PCM_OP_ORDER_SET_STATE

• PCM_OP_ORDER_SET_ATTR

• PCM_OP_ORDER_SET_BRAND

PCM_OP_ORDER_UPDATE also validates the change specified in the opcode against the /config/order_state object for that order type and brand. Invalid order states or state changes cause the opcode to fail.

The order life cycle is unique for each order type in each brand. The same order type could have different life cycles in different brands. See "Order Management and Brands" for more information.

Associating or Disassociating Orders with Master Orders

You can associate or disassociate orders with other orders. You can create orders and make them master orders by including or associating sub-orders with them. You can do this while creating the orders, or you can create orders and later associate them with other orders.

Applications call PCM_OP_ORDER_ASSOCIATE and the PCM_OP_ORDER_POL_ASSOCIATE policy opcode to associate and disassociate orders and create orders in different levels. A flag in the input flist determines whether the order is associated or disassociated. PCM_OP_ORDER_ASSOCIATE validates the associations against the order types, master orders, sub-orders, and brands in question. Invalid associations cause the opcode to fail. PCM_OP_ORDER_ASSOCIATE updates the order array to include or exclude sub-orders. See "Associating and Disassociating /order Objects".

Managing Order Attributes

Each order has a unique ID, the order ID, that identifies the order for tracking by the order management system. This order ID is used to identify orders, search for orders, create a request file, modify orders, and delete orders.

Note:

To modify or delete an order, the state of the order must be New.

You can add fields to /order objects for attributes specific to particular order types. For example, /order/voucher contains attributes specific to voucher cards.

Applications call PCM_OP_ORDER_SET_ATTR and the PCM_OP_ORDER_POL_SET_STATE policy opcode to set order attributes and order state. PCM_OP_ORDER_SET_ATTR can be used to change the common attributes mentioned above and the attributes introduced in subclasses. It cannot be used to change the order state or to cancel an order or brand association.

Deleting Orders

Orders can be deleted for a variety of reasons. You can call PCM_OP_ORDER_DELETE to remove the order object from the database when it is no longer needed.

During order deletion, the PCM_OP_ORDER_POL_DELETE policy opcode searches for the order by using the order ID. If the order ID is not found, the opcode generates an error. You can modify the policy to bypass the check and automatically remove the order object to be deleted.

Note:

If you delete a master order, the sub-orders associated with it are automatically deleted as well.

See "Associating or Disassociating Orders with Master Orders" for more information about master order–to–sub-order associations.

Tracking Order History

All order operations, such as order creation, state transitions, and changes to attributes, are recorded in the database as events. Recording events enables you to track the history of an order from a client application such as Customer Center or a custom order management system.

You can turn off event recording and turn on auditing to maintain order history without storing details. For information about choosing which events to record, see "Managing Database Usage" in BRM System Administrator's Guide. For an introduction to auditing and links to more detailed information, see "About Maintaining an Audit Trail of BRM Activity" in BRM Managing Customers.

Two BRM reports enable you to monitor the status and history of orders. See "About the BRM Reports Packages" in BRM Reports.

Managing the Order History Log

All operations related to the /order object, including order creation, setting order states, setting order attributes, and deleting orders, are logged in the database.

Customers can search the logging history for any /order object in the database. This data is used by different BRM components such as Customer Center and Pipeline Manager.

Installing the Order Management Framework

The Order Management framework software is included in both the Voucher Manager and the Inventory Manager installation packages.

The hardware and software requirements for Order Management framework software are the same as for Voucher Manager.

The default installation of Voucher Manager installs both the Voucher Manager and Order Management framework software. To install only the Order Management software, select Order Manager when prompted during a custom install.

For more information, see "Installing Voucher Manager" in BRM Telco Integration.

Follow the instructions in "Installing the Order Management Framework" section, if you do not use the Voucher Manager and use Inventory Manager.

Installing the Order Management Framework

To install Order Manager:

1. Download the software to a temporary directory (temp_dir).

   Important:

   • If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.

   • You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid "Out of Memory" error messages in the log file. For information, see "Increasing Heap Size to Avoid "Out of Memory" Error Messages" in BRM Installation Guide.

2. Go to the directory where you installed the Third-Party package and source the source.me file.

   Caution:

   You must source the source.me file to proceed with installation, otherwise "suitable JVM not found" and other error messages appear.

   Bash shell:

   source source.me.sh
     
   

   C shell:

   source source.me.csh
     
   

3. Go to the temp_dir directory and enter this command:

   7.5.0_InventoryMgr_platform_opt.bin
   

   where platform is the operating system name.

   Note:

   You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.

4. Follow the instructions displayed during installation.

   Note:

   The installation program does not prompt you for the installation directory if BRM or Inventory Manager is already installed on the machine and automatically installs the package at the BRM_Home location, where BRM_Home is the directory in which you installed BRM components.

5. Go to the directory where you installed the Inventory Manager package and source the source.me file:

   Bash shell:

   source source.me.sh
     
   

   C shell:

   source source.me.csh
     
   

6. Go to the BRM_Home/setup directory and run the pin_setup script.

   Note:

   The pin_setup script starts all required BRM processes.

Uninstalling the Order Management Framework

To uninstall the Order Management framework, run the BRM_Home/uninstaller/InventoryMgr/uninstaller.bin.

Order Management and Brands

The Order Management framework supports branding. For example, a Customer Service Representative (CSR) using Customer Center can see and assign orders only in brands for which they have permissions.

You implement branding by associating brands with both /order objects and the /config objects used to configure them. Each /order and /config object contains the POID of the /account object of the brand.

The brand affiliation of /order and /config objects is determined by the BRM login used to create them:

• For /order objects, this might be the login of a Customer Center user or the user of a bulk order creation tool.

• For /config objects (/config/order_state), the brand is determined by the login in the Infranet.properties file for the load utilities used to create the objects. See "About Defining the Order Life Cycle" for more information about the load utilities.

Access permissions ensure that only the logins associated with the correct brands can read, write, and create /order objects and their /config objects for the brand:

• /order objects have read permission set to Brand Lineage and write permission set to Ancestral Lineage. See "Branding Access Permissions".

• /config objects have read permission set to Brand, write permission set to Self, and create permission set to Brand Owner. See "Branding Access Permissions".

You can set up order management features to work differently for orders in different brands. For example, you might define a different life cycle for an order in Brand A than for the same order in Brand B. See "About Defining the Order Life Cycle" for more information.

You can change the brand affiliation of an /order object by using PCM_OP_ORDER_SET_BRAND and the PCM_OP_ORDER_POL_SET_BRAND policy opcode. The caller of the opcode must have access permissions that permit changing objects in both the old and new brands. In some cases this may require the use of a root login.

Order Management and Multischema Environments

The Order Management framework supports multischema environments, with some restrictions:

• An /order object and the corresponding /event/order objects are stored in the specified database schema when an order is created.

• The master order object cannot be linked to sub-orders that reside in other schemas.

• You cannot move /order objects from one schema to another. You can delete the objects and re-create them in another schema, but master order and sub-order associations are lost.

About Defining the Order Life Cycle

You define the life cycle for order objects in BRM by editing or creating a configuration file and then loading the data into a /config/order_state object in the database.

Each /config/order_state object contains definitions of the possible order states and state changes for one order type and brand. /config/order_state objects also contain information about which policy opcodes to call during state changes.

For detailed information about the syntax of the configuration file and running the load utility, see load_pin_order_state.

Note:

You must load the life cycle definitions into the database before using any order management features. Because order management configuration data is always customized, no default values are loaded during BRM installation.

While the life cycle for every /order object is unique, the general pattern for all /order objects is the same:

• During order creation, an /order object moves from state 0 to an initial state that is defined for that order type and brand.

• During the life of the /order object, it moves from state to state in the manner defined in a /config/order_state object. For example, an order might be able to move from the New state to the Request state, but not directly from the New state to the Received state. Each order type and brand has its own /config/order_state object, so you can define different life cycles to meet your business needs.

• At the end of the working life of the /order object, it moves into a final state such as Received or Cancelled. Depending on your business needs, the object could also be deleted to save space.

  Note:

  You can delete an order only when its order state is New.

There can be any number of order states, each of which is assigned a number in the order state configuration file. State 0 is reserved for the Raw state, but other numbers can be freely assigned.

There are four state types that correspond to the stages in the general pattern described above. These state types are defined in the pin_order.h header file and cannot be changed.

• State 0 indicates that the order is in Raw state.

• State 1 indicates that the order is in Init state.

• State 2 indicates that the order is in Normal state.

• State 3 indicates that the order is in End state.

When you define order states, they must be assigned to one of these types:

• Raw: There can be only one order state of this type for each order type and brand. /order objects are in raw state only during the creation process. They can never be saved in the raw state. Raw states can transition only to Init states.

• Init: This state type is for states in which the object is first saved to the database. There can be more than one initial state for a particular order type and brand. For example, you might want the order to be initialized to one state when created by a batch order creation tool and to another state when created by a CSR using a GUI tool. Init states can transition to Init, Normal, or End states. The order state New uses the Init state type.

• Normal: Normal order states are those that occur between the object's initial state and its end state. You can think of these as the working states for the order. There can be any number of Normal order states. Normal states can transition to Init states, other Normal states, and End states. The order states Request and Partially Received use the Normal state type.

• End: Orders cannot transition from End states. Because there are many possible end-of-life scenarios, you can include any number of End states. The order states Received and Cancelled use the End state type.

A typical order moves through the following states:

• New: The /order objects have this state when the order is created.

• Request: The /order objects have this state when an order is sent to the manufacturer for order creation.

• Partially Received: The /order objects have this state when the order is partially received.

• Received: The /order objects have this state when the order is completely received.

• Cancelled: The /order objects have this state when the order is canceled.

  Note:

  Only orders that have the order state New can be canceled.

When you define an order life cycle, be sure to consider all the stages in the life cycle of the order and all the possible relationships between them. You should also consider the level of detail that is useful to track in your order management system.

Figure 22-1 shows a simple order life cycle for voucher cards. The life cycles for your orders may be more complex depending on the characteristics of the orders and your business needs.

Figure 22-1 Simple Order Life Cycle for Voucher Cards

Description of ''Figure 22-1 Simple Order Life Cycle for Voucher Cards''

Because /config/order_state objects are brand aware, you must load an object for each unique combination of order type and brand. For example, if you have two order types (A and B) that occur in two brands (1 and 2) and a third order type (C) that occurs only in Brand 1, you must load /config/order_state objects for these five combinations: A1, A2, B1, B2, and C1.

If the state changes for an order type are the same for all brands, you can create a single /config/order_state object for that order type by using the root login when you run load_pin_order_state. The order management opcodes automatically check the /config/order_state object associated with root if they can't find an object associated with an order's brand. See "Order Management and Brands" for more information.

The names you use for order states can be localized for display in GUI applications. You must define the state names as text strings and load the definitions into the database by using the load_localized_strings utility.

Defining an Order Life Cycle

To define the life cycle for an order type in a particular brand:

1. If necessary, edit the infranet.connection entry in the BRM_Home/apps/order_management/Infranet.properties file to use a login associated with the brand you are working on.

2. Enter order state change definitions in a new text file or edit the BRM_Home/sys/data/config/pin_order_state file.

   See load_pin_order_state for information about the syntax of the file.

   Caution:

   The load_pin_order_state utility overwrites existing order states for an order type and brand. If you are updating order states, you cannot load new order states only. You must load complete sets of order states for the order type and brand each time you run the load_pin_order_state utility.

3. Save the configuration file.

   Tip:

   For ease of maintenance, use a file name that reflects the order type and brand.

4. Use the following command to load the pin_order_state file:

   load_pin_order_state state_change_file
     
   

   where state_change_file represents the path and name of the configuration file you saved.

5. Restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

To verify that the state change file was loaded, you can display the /config/order_state objects by using the Object Browser, or use the robj command with the testnap utility. (See "Reading an Object and Writing Its Contents to a File".)

Creating Custom Order Management Systems

You can create custom order management systems using the Order Management framework. An order management system can be a separate, standalone application that performs all necessary tasks, or it can be an enabling application that connects BRM to an existing order management system.

"Adding New Client Applications" provides a general overview as well as information about writing applications in C. Other sections provide information about additional programming languages.

You need to complete some or all of the following tasks to implement an order management system:

1. Create a subclass of the /order storable class for every new order type. Each subclass should include fields for the unique attributes of the order type.

   You use Storable Class Editor to create fields and classes. See "Creating Custom Fields and Storable Classes".

2. If necessary, write a new Facility Module (FM) for any unique functionality required by your order management system.

   See "Writing a Custom Facilities Module".

3. If necessary, modify the Order FM policy opcodes to customize the default order management functionality.

   See "Adding and Modifying Policy Facilities Modules" for general information and "Order FM Policy Opcodes" in BRM Developer's Reference for specific information about the Order Manager policy opcodes.

4. Write a custom application that calls the Order Manager standard and policy opcodes as well as any custom opcodes you created.

   See "Adding New Client Applications" for general information as well as information about writing applications in C.

5. Define the life cycles and order associations for your orders.

   See "About Defining the Order Life Cycle" and "Associating or Disassociating Orders with Master Orders".

About the Order Management Opcodes

Use the following opcodes to manage orders:

• To create an order, use PCM_OP_ORDER_CREATE. See "Creating /order Objects".

• To process an order request from a vendor or manufacturer, use PCM_OP_ORDER_PROCESS. See "Processing Order Response Files".

• To associate an order with a master order or a sub-order, use PCM_OP_ORDER_ASSOCIATE. See "Associating and Disassociating /order Objects".

• To update the state, brand, or attributes of an existing order, use PCM_OP_ORDER_UPDATE. See "Updating /order Objects".

• To delete an existing order, use PCM_OP_ORDER_DELETE. See "Deleting /order Objects".

  Important:

  These standard opcodes call Order FM policy opcodes prior to committing changes to the database. By default, the policies check whether the Portal object ID (POID) type is voucher and, if it is, call Voucher FM policy opcodes. However, you can customize the Order FM policy opcodes to perform additional validation. For information about Voucher Manager, see "About Managing Voucher Inventory" in BRM Telco Integration.

Creating /order Objects

Use PCM_OP_ORDER_CREATE to create an /order object. See "Creating Orders".

This opcode can be called by a custom order creation application or by Customer Center.

This opcode takes a type-only POID as input, which specifies the order type and the target database. PCM_OP_ORDER_CREATE performs these operations:

1. Calls the PCM_OP_ORDER_POL_CREATE policy opcode for validation. This opcode checks the POID type and calls other related Facilities Modules (FMs) and policy FMs to perform any validation checks those opcodes require. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_CREATE policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_CREATE policy opcode to validate information in the input flist.

2. Sets the brand of the /order object based on the brand of the creator.

3. Creates an /order object of the type specified in the input flist. This object includes all mandatory attributes for the order type.

4. Calls PCM_OP_ORDER_SET_STATE to set the initial order state. See "Setting the State in /order Objects".

5. If events are being recorded, generates an /event/order/create object.

6. If necessary, calls PCM_OP_ORDER_ASSOCIATE to associate the order with any master orders or sub-orders. See "Associating and Disassociating /order Objects".

7. Returns the POID of the /order object.

PCM_OP_ORDER_CREATE stops processing under these circumstances:

• When the PCM_OP_ORDER_POL_CREATE policy opcode fails.

• When PCM_OP_ORDER_SET_STATE fails.

If PCM_OP_ORDER_CREATE is not successful, it logs an error in the CM pinlog file, indicating the reason for the failure. The transaction is rolled back and no /order object is created.

Customizing Order Creation

Use the PCM_OP_ORDER_POL_CREATE policy opcode to customize any validation or checks to be performed before the actual processing starts.

For example, if orders of a particular type require an order ID with certain characteristics, you can validate the ID supplied by the input flist. Similarly, you can use the opcode to ensure that all mandatory attributes of a particular order type are included in the new object.

Processing Order Response Files

Use PCM_OP_ORDER_PROCESS to process order response files from the vendor or manufacturer. This opcode creates the devices in the BRM database and then updates the order status. See "Processing Order Response Files".

PCM_OP_ORDER_PROCESS performs these operations:

1. Retrieves data about the order from the /order object.

2. Calls the PCM_OP_ORDER_POL_PROCESS policy opcode for validation. This policy opcode calls other FMs and Policy FMs depending on the POID type passed in. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_PROCESS policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_PROCESS policy opcode to validate information in the input flist.

3. Calls PCM_OP_DEVICE_CREATE to create the specified devices in the BRM database. See "Managing Devices with BRM".

4. Calls PCM_OP_ORDER_UPDATE to update the status of the /order object.

5. If events are being processed, generates an /event/order/process object.

6. Returns the POID of the /order object.

PCM_OP_ORDER_PROCESS stops processing under these circumstances:

• When a /config/order_state object cannot be found for this order type.

• When the order state change is invalid based on the /config/order_state object for this order type.

Customizing Order Processing

The PCM_OP_ORDER_POL_PROCESS policy opcode allows you to customize any validation or checks to be performed before the actual processing starts.

You can use this opcode to perform validation of /order objects when you process the order.

Associating and Disassociating /order Objects

Use PCM_OP_ORDER_ASSOCIATE to associate or disassociate a sub-order with a master order. For information, see "Associating or Disassociating Orders with Master Orders".

You can associate or disassociate orders during account creation or when required. When associating sub-orders with master orders, it contains the POID of the master order.

PCM_OP_ORDER_ASSOCIATE performs these operations:

1. Determines whether to associate or disassociate by checking the PIN_FLD_FLAGS field:

   • When the flag is set to 1, the opcode associates the specified objects.

   • When the flag is set to 0, the opcode disassociates the specified objects.

2. For association only, validates the order–to–sub-order association. This validation includes ensuring that the orders have the same brand.

3. Calls the PCM_OP_ORDER_POL_ASSOCIATE policy opcode for validation. This policy opcode calls other FMs and policy FMs depending on the POID type passed in. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_ASSOCIATE policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_ASSOCIATE policy opcode to validate information in the input flist.

4. Associates or disassociates the objects.

5. If events are being recorded, generates an /event/order/associate or /event/order/disassociate object.

6. Returns the POID of the /order object.

PCM_OP_ORDER_ASSOCIATE stops processing if an order listed in the input flist already exists in the /order object.

Customize How to Validate Association and Disassociation

Use the PCM_OP_ORDER_POL_ASSOCIATE policy opcode to customize any validation, in addition to the standard validation, or any checks to be performed before the actual order association or disassociation starts.

For example, you could limit the number of associations for particular order types or trigger a state change after certain associations or disassociations.

Updating /order Objects

Use PCM_OP_ORDER_UPDATE to update the brand, state, or attributes of an existing /order object.

This opcode takes as input the POID of the /order object to change, the program that is calling the opcode, and the fields to change, along with their new values. If the opcode is changing the attributes of an /order subclass, it can include fields introduced in the subclass.

PCM_OP_ORDER_UPDATE is a wrapper opcode that calls other opcodes to perform the actual modification to the order. The opcode determines whether to update the brand association, order state, or order attributes by checking the fields passed in on the input flist:

• When the PIN_FLD_ACCOUNT_OBJ field is passed in, the opcode changes the brand association by calling PCM_OP_ORDER_SET_BRAND. See "Changing /order Object Brand Associations".

• When the PIN_FLD_STATUS field is passed in, PCM_OP_ORDER_UPDATE changes the order state by calling PCM_OP_ORDER_SET_STATE. See "Setting the State in /order Objects".

• When the PIN_FLD_EXTENDED_INFO array is passed in, the opcode changes the order attributes by calling PCM_OP_ORDER_SET_ATTR. See "Changing /order Object Attributes".

PCM_OP_ORDER_UPDATE stops processing under these circumstances:

• When the PCM_OP_ORDER_POL_SET_ATTR, PCM_OP_ORDER_POL_SET_BRAND, or PCM_OP_ORDER_POL_SET_STATE policy opcode fails.

• When an attribute to change doesn't exist in the /order object.

Changing /order Object Brand Associations

Use PCM_OP_ORDER_SET_BRAND to change an order's brand association. This opcode is called by PCM_OP_ORDER_UPDATE to update an existing order. See "Order Management and Brands".

Important:

A master order and its associated sub-orders must all use the same brand.

All /order objects have Ancestral Lineage write permissions, so the caller of PCM_OP_ORDER_SET_BRAND must be in the ancestral lineage of both the old and new brands. If the old and new brands are too distantly related, the opcode caller must have root permissions.

PCM_OP_ORDER_SET_BRAND takes as input the POID of the /order object to change, the program that is calling the opcode, and the /account object of the new brand.

PCM_OP_ORDER_SET_BRAND performs these operations:

1. Calls the PCM_OP_ORDER_POL_SET_BRAND policy opcode for validation. This policy opcode calls other FMs and policy FMs depending on the POID type passed in. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_SET_BRAND policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_SET_BRAND policy opcode to validate information in the input flist.

2. Validates permissions to ensure that the caller has permissions for both the new and old brands.

3. Replaces the old brand account value with the new one.

4. If events are being recorded, generates an /event/order/brand object.

5. Returns the POID of the /order object.

PCM_OP_ORDER_SET_BRAND stops processing under these circumstances:

• When the caller does not have permissions for both the old and new brands.

• When the PCM_OP_ORDER_POL_SET_BRAND policy opcode fails.

Customizing Brand Association

The PCM_OP_ORDER_POL_SET_BRAND policy opcode allows you to customize any validation or checks to be performed before the actual processing starts.

You can use this policy opcode to provide validation or customization of brand changes for a given order ID. For example, you could limit brand changes to certain order types or situations.

Setting the State in /order Objects

Use PCM_OP_ORDER_SET_STATE to set or change the state of an /order object. During the processing of this opcode, there are two opportunities to call policy opcodes for validation:

• The first policy call takes place during the state change itself, just before the transaction is committed to the database.

• The second occurs just after the transaction that changes the order state.

You specify which policy opcodes to call for each state change in the same configuration file where you define the order life cycle. For each state change, you can specify an opcode for one, both, or neither of the two potential policy calls.

The PCM_OP_ORDER_POL_SET_STATE policy opcode is supplied as the default policy opcode for order state changes. You can create any number of custom policy opcodes to replace or supplement it. You enter the numbers of the policy opcodes in the configuration file.

For more information, see "Managing the Order Life Cycle".

PCM_OP_ORDER_SET_STATE takes as input the POID of the /order object, the calling program, the old state ID, and the new state ID. It then performs these operations:

1. Checks the validity of the state change based on the /config/order_state object for this order type and brand. If the state change is not allowed, this opcode stops processing.

2. Calls the policy opcode specified in /config/order_state for the in-transition event.

3. Changes the PIN_FLD_STATUS field in the /order object to the new state.

4. Calls the policy opcode specified in /config/order_state for the post-transition event.

5. If events are being recorded, generates an /event/order/state object.

6. Returns the POID of the /order object.

PCM_OP_ORDER_SET_STATE stops processing under these circumstances:

• When the order state change is not valid based on the /config/order_state object for this order type.

• When a /config/order_state object cannot be found for this order type.

• When the input flist attempts to change the order from a Raw state type to any state type other than Init or attempts to change the order from an End state type to any other state.

Customizing How to Validate State Changes

The PCM_OP_ORDER_POL_SET_STATE policy opcode allows you to customize any validation or checks to be performed before the actual processing starts.

You can customize this policy opcode to provide additional validation or functionality during order state changes.

Changing /order Object Attributes

Use PCM_OP_ORDER_SET_ATTR to change the attributes for an existing /order object. This opcode is called by PCM_OP_ORDER_UPDATE to update the object's attributes. See "Managing Order Attributes".

Different order types can have different attributes. The attributes common to all orders, such as the text description stored in the PIN_FLD_DESCR field, are contained in the main /order object. Attributes specific to particular order types are stored in their subclasses.

Note:

You cannot use PCM_OP_ORDER_SET_ATTR to change the brand association, order state, or order association. If the input flist includes these fields, they are ignored.

PCM_OP_ORDER_SET_ATTR performs these operations:

1. Calls the PCM_OP_ORDER_POL_SET_ATTR policy opcode for validation. This policy opcode calls other FMs and policy FMs based on the POID type passed in. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_SET_ATTR policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_SET_ATTR policy opcode to validate information in the input flist.

2. Updates the /order object to include the new attribute values.

3. If events are being recorded, generates an /event/order/attribute object.

4. Returns the POID of the /order object.

PCM_OP_ORDER_SET_ATTR stops processing under these circumstances:

• When the PCM_OP_ORDER_POL_SET_ATTR policy opcode fails.

• When an attribute to change doesn't exist in the /order object.

Customizing the opcode

The PCM_OP_ORDER_POL_SET_ATTR policy opcode allows you to customize any validation or checks to be performed before the actual processing starts.

You can use this opcode to perform validations or to set the attributes for the order object. For example, you can write code to validate the order ID in the input flist to conform to the pattern for a particular order type.

Deleting /order Objects

Use PCM_OP_ORDER_DELETE to delete an /order object. See "Deleting Orders".

PCM_OP_ORDER_DELETE performs these operations:

1. Calls the PCM_OP_ORDER_POL_DELETE policy opcode for validation. This policy opcode calls other FMs and policy FMs based on the POID type. For example, if the POID type is voucher, the PCM_OP_ORDER_POL_DELETE policy opcode calls the PCM_OP_VOUCHER_POL_ORDER_DELETE policy opcode to validate information in the input flist.

2. If the specified object is a sub-order, calls PCM_OP_ORDER_ASSOCIATE to disassociate the object from the master order.

3. Deletes the specified /order object from the BRM database.

4. If events are being recorded, generates an /event/order/delete object.

5. Returns the POID of the /order object.

PCM_OP_ORDER_DELETE stops processing if the PCM_OP_ORDER_POL_DELETE policy opcode fails.

Customizing How to Delete Orders

The PCM_OP_ORDER_POL_DELETE policy opcode allows you to customize any validation or checks to be performed before the actual processing starts.

You can use this policy opcode to customize the order-deletion process. For example, you can disable the service association check that is performed by default.