Customizing the Billing Care Actions Menu

About the Billing Care Actions Menu

The Billing Care Actions menu is defined in XML format. Example 25-1 shows a sample portion of the XML Actions menu definition file. The <menu> tags represent a menu, and the <item> tags inside <menu> tags represent the submenus of that menu.

Example 25-1 Sample Portion of the Actions Menu Definitions XML File

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<menu-definition xmlns="http://xmlns.oracle.com/cgbu/schemas/BusinessObjs">
    <menu id="menu-general">
        <header-key>actions_menu.ACCOUNT</header-key>
        <contents>
            <item id="menu-item-account-profile">
                <label-key>actions_menu.ACCOUNT_PROFILE</label-key>
                <description-key>actions_menu.ACCOUNT_PROFILE_SHORT_DESCRIPTION</description-key>
                <!--"permission-key" and "action-key" are used for enabling/disabling menu using Authorization
                    The corresponding values should not be modified.
                    This applies to every entry in the xml
                -->
                <permission-key>AccountResource</permission-key>
                <action-key>View</action-key>
                <version>1.0</version>
            </item>
            <item id="menu-item-account-status">
                <label-key>actions_menu.ACCOUNT_STATUS</label-key>
                <description-key>actions_menu.ACCOUNT_STATUS_SHORT_DESCRIPTION</description-key>
                <permission-key>AccountResource</permission-key>
                <action-key>Transition</action-key>
                <version>1.0</version>
            </item>
        </contents>
    </menu>
    <menu id="menu-pay">
        <header-key>actions_menu.PAYMENTS</header-key>
        <contents>
            <item id="menu-item-make-payment">
                <label-key>actions_menu.MAKE_PAYMENT</label-key>
                <description-key>actions_menu.MAKE_PAYMENT_SHORT_DESCRIPTION</description-key
                <permission-key>PaymentResource</permission-key>
                <action-key>Make</action-key>
                <version>1.0</version>
            </item>
            <item id="menu-item-allocate-payment">
                <label-key>actions_menu.ALLOCATE</label-key>
                <description-key>actions_menu.ALLOCATE_SHORT_DESCRIPTION</description-key>
                <permission-key>PaymentResource</permission-key>
                <action-key>Allocate</action-key>
                <version>1.0</version>
            </item>
        </contents>
    </menu>
</menu-definition>

The following Actions menu element definitions are provided to assist you with customizing the Actions menu:

action-key holds the action value for the corresponding resource (for example, Make, Allocate, and so on).
contents.item.label-key represents the resource bundle key for entries within the submenus.
description-key represents a submenu description that appears below a menu label.
header-key represents the resource bundle key for the entries in the Actions menu (Account, Payments, and so on) and the header within the submenus.
id is used as the element ID for the menus and anchor links representing the menu entries. This may be useful for the associated JavaScript code that you can write for custom menu entries.
label-key represents the menu label.
permission-key reflects the authorization key that controls access to the menu entry. This is used to hold the resource value (for example, PaymentResource, AdjustmentResource, and so on).

Mapping Label and Description Key Values to the Resource Bundle

The label-key and description-key values use either the text string included within the tag, or a referenced value mapped to the Billing Care resource bundle. When mapping these keys to the resource bundle, use the following format:

actions_menu.trans-unit ID

where trans-unit ID represents the label defined in the resource bundle. See "Customizing Billing Care Labels" for more information on customizing the resource bundle for your environment.

About Customizing the Actions Menu

You can customize the Actions menu in the following ways:

The Billing Care SDK includes a sample Actions menu customization in the SDK_home/samples/ActionMenu directory. Use this sample to assist you in customizing the Actions menu.

Setting Up NetBeans IDE for Customizing the Actions Menu

Customizing Billing Care Actions menu requires creating a custom XML configuration file (CustomActionMenu.xml). This file contains the configuration for your custom menu structure.

To customize Billing Care invoice presentation:

Copy the default ActionMenu.xml file from SDK_home/references to a custom file named CustomActionMenu.xml in your myproject/web/WEB-INF/custom/configurations directory.
Customize the Actions menu by using the CustomActionMenu.xml file as described in the following sections.
Save and close the CustomActionMenu.xml file.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Removing Actions Menu Items

Use the following procedures to remove Actions menu items:

Removing an Existing Actions Menu Submenu

To remove an existing Actions menu submenu:

Open the CustomActionMenu.xml file in an editor.

Delete the corresponding <item> element in CustomActionMenu.xml for the submenu you want to remove.

For example, to remove Account Status from Account menu, remove the following <item> element:

<item id="menu-item-account-status">
   <label-key>actions_menu.ACCOUNT_STATUS</label-key>
   <permission-key>AccountResource</permission-key>
   <action-key>Transition</action-key>
   <version>1.0</version>
</item>

Save and close the CustomActionMenu.xml file.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Removing an Existing Actions Menu

To remove an existing menu:

Open the CustomActionMenu.xml file in an editor.

Delete the corresponding <menu> block for the menu you want to remove.

For example, to remove the Account menu, remove the following <menu> element:

<menu id="menu-general">
       <header-key>actions_menu.ACCOUNT</header-key>
       <contents>
           <item id="menu-item-account-profile">
               <label-key>actions_menu.ACCOUNT_PROFILE</label-key>
               <!--"permission-key" and "action-key" are used for enabling/disabling menu using Authorization
                   The corresponding values should not be modified.
                   This applies to every entry in the xml
               -->
               <permission-key>AccountResource</permission-key>
               <action-key>View</action-key>
               <version>1.0</version>
           </item>
           <item id="menu-item-account-status">
               <label-key>actions_menu.ACCOUNT_STATUS</label-key>
               <permission-key>AccountResource</permission-key>
               <action-key>Transition</action-key>
               <version>1.0</version>
           </item>
       </contents>
   </menu>

Save and close to CustomActionMenu.xml file.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Rearranging Actions Menu Items

Use the following procedures to remove Actions menu items:

Rearranging Actions Menu Submenu Items

To rearrange Actions menu submenu items:

Open the CustomActionMenu.xml file in an editor.

Change the order of corresponding submenu <item> tags.

For example, to get Account Status first and then Account Profile second in the Account menu:

<menu id="menu-general">
        <header-key>actions_menu.ACCOUNT</header-key>
        <contents>
            <!-- Account status comes first -->
            <item id="menu-item-account-status">
                <label-key>actions_menu.ACCOUNT_STATUS</label-key>
                <permission-key>AccountResource</permission-key>
                <action-key>Transition</action-key>
                <version>1.0</version>
            </item>
            <item id="menu-item-account-profile">
                <label-key>actions_menu.ACCOUNT_PROFILE</label-key>
                <!--"permission-key" and "action-key" are used for enabling/disabling menu using Authorization
                    The corresponding values should not be modified.
                    This applies to every entry in the xml
                -->
                <permission-key>AccountResource</permission-key>
                <action-key>View</action-key>
                <version>1.0</version>
            </item>           
        </contents>
    </menu>

Save and close to CustomActionMenu.xml file.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Rearranging Actions Menu Items

To rearrange Actions menu items:

Open the CustomActionMenu.xml file in an editor.
Change the order of corresponding <menu> tags to the order you want the menus to be displayed.

For example, to get Payments as the first menu and Account as the second menu:
```
<menu id="menu-pay">
    
 </menu>
 <menu id="menu-general">
     
 </menu>
```
Save and close to CustomActionMenu.xml file.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Renaming Actions Menu and Submenu Items

Use the following procedures to rename Actions menu items:

Renaming Actions Menu Submenu Items

To rename an Actions menu submenu item:

Open the CustomActionMenu.xml file in an editor.
Change the value of <label-key> for the submenu item you want to rename.
Save and close to CustomActionMenu.xml file.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Renaming Actions Menu Items

To rename an Actions menu item:

Open the CustomActionMenu.xml file in an editor.
Change the value of <header-key> for the menu item you want to rename. Note the header key for the menu changed.
Save and close to CustomActionMenu.xml file.
Find the header key in the resource bundle and follow the steps in "Customizing the Resource Bundle" to rename the Actions menu items.
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Adding Actions Menu Items

Adding Actions menu and submenu items requires you to add new <menu> and <item> elements in your CustomActionMenu.xml file and create a custom view model to support your new menus and submenus.

To add Actions menu or submenu items:

Open the CustomActionMenu.xml file in an editor.

Add new <menu> and <item> elements as required under the  comment.

For example:

<!-- Custom block to be added in the CustomActionsMenu.xml -->
    <menu id="menu-pay">
        <header-key>actions_menu.PAYMENTS</header-key>
        <contents>
           <!-- existing content remains -->
            <!-- Add  a new menu item under payments -->
            <item id="menu-item-new-custom-item">
                <label-key>New Custom Menu Item</label-key>
                <permission-key>PaymentResource</permission-key>
                <!-- If we are not using ant existing action-key, this NewCustomActionKey must be configured in the OPSS environment -->
                <action-key>NewCustomActionKey</action-key>
                <version>1.0</version>
            </item>  
        </contents>
    </menu>

Create a new custom view model file to support the new Actions menu items you created (for example, customMenuViewModel.js) in the myproject/web/js directory where myproject is the NetBeans IDE project containing your Billing Care customizations.
Write and bind click events in the custom view model file using the same ids that you used in the CustomActionMenu.xml file:
```
$('#menu-item-new-custom-item').click(function(e){
   //implementation goes here.
   }
);
```
If your menu or submenu additions require custom logic, extend Billing Care using the SDK to support the required functions. See "Extending and Creating Billing Care REST Resources" for more information on extending Billing Care.
Copy the default registry.js file from SDK_home/references to a custom registry file named customRegistry.js in your myproject/web/custom directory, where myproject is your NetBeans IDE project containing your Billing Care customizations. This file contains the module definition using your custom view model (JavaScript).
Add the definition for your custom view model in the customRegistry.js file, located in your myproject/web/custom directory.

For example:
```
var CustomRegistry = {
   customActionMenus: {
      viewmodel: '../custom/viewmodels/MenuEventHandlerViewModel'
   }
};
```
Right-click your NetBeans IDE project and select Clean and Build.
Package and deploy your invoice presentation customizations to your Billing Care domain.

For more information, see "Packaging and Deploying Customizations".
Verify your changes in Billing Care.

Adding Action Menu Items in Payment Suspense

The Payment Suspense action menu can be customized with additional menu items. To add custom Payment Suspense action menu items, use the same procedure described in "Adding Actions Menu Items".

The Billing Care SDK includes a sample Payment Suspense Actions menu customization in the SDK_home/samples/PaymentSuspenseDetailsActionsMenu directory. Use this sample to assist you in customizing the Payment Suspense Actions menu.