Skip Headers
Oracle® Communications Order and Service Management Developer's Guide
Release 7.2.2

E35419-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 Using Custom Menu Items and Actions

This chapter describes the Oracle Communications Order and Service Management (OSM) Custom Menu and Action feature, which allows you to configure custom menu items and actions that are called from the context menu of the Task Web client Worklist and Query Result pages.

About Custom Menu Items and Actions

A custom menu action calls customer-specific business logic, for example, enabling a print job of tasks in the Worklist. The custom business logic can easily interact with the OSM server through the XML API.

You define custom menu items and actions using a model in an XML file. Actions are defined globally across all cartridges, and may be called for any task or group of tasks. The action is available to all users. Actions that call the XML API are done within the Web client session, so access privileges to the API are based on the Web client user's workgroup privileges.

Additionally, API users must belong to a WebLogic group that provides privilege to access the APIs. For custom menu and action items, that WebLogic group is OMS_xml_api. So, to access the APIs through custom menu items and actions, the API user must belong to the WebLogic group OMS_xml_api.

About the File Name and Location

The metadata definition for custom menu action is supported through a standalone configuration file that is loaded and run at runtime. The OSM Administrator application (or an Ant task in the Cartridge Development Kit) can be used to trigger a reload of the configuration file.

The name and location of the custom menu action file is defined in the oms-config.xml file.

A working model, which includes a sample configuration file, Javascript file, and ReadMe, is available in the OSM_home/SDK/Samples/CustomMenuAndAction directory.

About the Model Definition

The definition of the model must follow the XML schema menuAction.xsd located in the OSM_home/SDK/XMLImportExport directory. The action and menuItem elements are described below.

Action Definition

Table 7-1 lists the action elements.

Table 7-1 Action Elements

Element Description

name

The name of the action referenced by the menu item.

xsi:type

There are three types of actions:

javascriptActionType - Defines a Javascript function as part of the <implementation> element. The function may be embedded directly in the element, in which case it should not be wrapped in a function name () {} construction, or it may be located in an external file which can be called from the <implementation> element.

orderContextActionType - Similar to javascriptActionType, can make use of Javascripts in the same way. In addition, has an object named orderContext which is accessible from within the Javascript. Refer to this object as part of the function. If the function is defined in an external file and the <implementation> contains a call to that function, pass orderContext as a parameter to the function.

uriActionType - Forwards you to the supplied URI, which opens in a new window in the browser. The URI is supplied as part of the <implementation> element.

description

The description of the action that appears on the context menu when no menu item description is supplied.

hint

The tool tip associated with the action.

icon

The icon associated with the action. Icons must be packed as part of the oms.ear file (oms.ear/oms.war/images).

implementation

The implementation of the action, e.g. Javascript function, orderContext, URI. May also contain a href, which is a URI pointing to a Javascript file.

uri

The path to a local directory, Web page address, or any point of content.


OrderContext and Orders

An orderContextActionType action is supplied with an object named orderContext. This object contains an array of orders which, in turn, contains information about the orders for which the action was called. Table 7-2 shows the method calls that can be made on the orderContext and order objects.

Table 7-2 orderContext and Orders

Object Methods Description

orderContext

getOrders()

Call this method to get the selected orders.

order

getOrderId()

Call this method to get the order ID for the order.

order

getOrderHistId()

Call this method to get the order history ID for the order.

order

getOrderTypeId()

Call this method to get the order type ID for the order.

order

getOrderSourceId()

Call this method to get the order source ID for the order.

order

getState()

Call this method to get the state of the order.


Calling the XML API

The function, callXmlApi(), makes it easier for action implementations to call the XML API. The function takes the XML API request document as an argument and returns the response XML document.

Sample Action Implementations

This section provides some samples of the different types of actions that you can configure in your custom action and menu XML file.

<action name="get_worklist_through_xml_api" xsi:type="javascriptActionType"> 
    <description>Get worklist though XML API</description> 
    <hint>An XML API call</hint> 
    <icon>/oms/images/delete_node.gif</icon> 
    <implementation>
        var callString=prompt("Please enter the XML API statement", "<Worklist.Request xmlns='urn:com:oracle:oms:xmlapi:1'> </Worklist.Request>"); var returnDoc=callXmlApi(callString); alert("Returned document: " + returnDoc.xml);
    </implementation> 
</action>
<action name="test_order_context" xsi:type="orderContextActionType"> 
    <description>Test Order Context</description> 
    <implementation>
        var orders=orderContext.getOrders();var callString="<GetOrder.Request xmlns='urn:com:oracle:oms:xmlapi:1'>";callString = callString + "<OrderID>" + orders[0].getOrderId() + "</OrderID>";callString = callString + "<Accept>false</Accept>";callString = callString + "<OrderHistID>" + orders[0].getOrderHistId() + "</OrderHistID>";callString = callString + "</GetOrder.Request>";returnDoc = callXmlApi(callString);alert('result: ' + returnDoc.xml);
    </implementation> 
</action> 

<action name="test_js_file" xsi:type="orderContextActionType"> 
    <description>Test Order Context</description> 
    <implementation href="file:///$bea_home/user_projects/domains/provisioning/foo.js">
        test_js_file(orderContext);
    </implementation> 
</action> 

<action name="go_to_about" xsi:type="uriActionType"> 
    <description>Show OSM About</description> 
    <icon>/oms/images/mslv_logo1.jpg</icon> 
    <uri>/oms/about</uri> 
</action>

Menu Item Definition

Table 7-3 Menu Item Elements

Attribute Description

name

The name of the menu item (internal reference only).

description

The description of the menu item that appears on the context menu.

enabled

Can be set to true() or false() when used in conjunction with an XPath to other fields. Not supported in this version.

visible

Can be set to true() or false() when used in conjunction with an XPath to other fields. Not supported in this version.

displayStyle

The display style of the menu item on the context menu, either icon, or text, or both. References the action icon and/or description.

action

Reference to the action being called.


Sample Menu Item Definition

<menuItem name="get_worklist"> 
    <description>Get worklist through XML API</description> 
    <enabled>true()</enabled> 
    <visible>true()</visible> 
    <displayStyle>ICON TEXT</displayStyle> 
    <action> 
        <name>get_worklist_through_xml_api</name> 
    </action> 
</menuItem>

Setting Up the Environment

Once you have defined the elements in your configuration file, you must set up the environment before running the file. There are three methods for doing this:

To configure your environment, you must perform the steps in "Setting Up the oms-config.xml File" and only one of the following sections:

Setting Up the oms-config.xml File

All three methods of environment configuration require that you set up the oms-config.xml file. There are two ways of managing this file:

  • Using an external oms-config.xml file which is the recommended easy-access method.

  • Storing the oms-config.xml file in oms.ear which requires unpacking and repacking oms.ear to modify the file.

For the file system path method, you must edit the oms-config.xml file for each environment where the absolute path to the file is different. For the XML Catalog methods you should only need to perform this procedure once.

See OSM System Administrator's Guide for more information about editing the oms-config.xml file.

  1. Locate the following section of the oms-config.xml file:

    <oms-parameter>
        <oms-parameter-name>custommenuaction_model_location</oms-parameter-name>
        <oms-parameter-value/>
    </oms-parameter>
    
  2. Update the <oms-parameter-value> tag. The value you use here depends on the environment configuration method you are using.

    • If you are using the file system path method, update the value with the exact path to the configuration file for the current environment. You must perform this procedure for each environment that has a different file path.

      <oms-parameter>
          <oms-parameter-name>custommenuaction_model_location</oms-parameter-name>
          <oms-parameter-value>
              /opt/OSM/CustomMenu/custom_menu_action_model.xml
          </oms-parameter-value>
      </oms-parameter>
      
    • If you are using the XML Catalog (Static Relative Location) method, you use a relative location based on osmmodel and referring to a directory in the Studio workspace.

      <oms-parameter>
          <oms-parameter-name>custommenuaction_model_location</oms-parameter-name>
          <oms-parameter-value>
              osmmodel://cartridge_name/cartridge_version/resources/filename.xml
          </oms-parameter-value>
      </oms-parameter>
      

      where cartridge_name and cartridge_version represent the name and version of the cartridge where you are planning to include the custom files, and filename.xml is the file with your XML model (for example, custom_menu_action_model.xml).

    • If you are using the XML Catalog (rewriteURI) method, you use a URI that you have determined for this task. It does not have to be a valid URL or any location where the file is located. It will be overwritten with a valid value automatically at runtime.

      <oms-parameter>
          <oms-parameter-name>custommenuaction_model_location</oms-parameter-name>
          <oms-parameter-value>
              http://example.org/somewhere/filename.xml
          </oms-parameter-value>
      </oms-parameter>
      

      where example.org/somewhere represents a namespace you are using as a convention to refer to this file and filename.xml is the file with your XML model (for example, custom_menu_action_model.xml).

File System Path Environment Configuration Method

You must perform the procedure below for each server environment.

  1. Edit your custom menu and action configuration XML file to ensure that it contains the correct location of any external files referenced in it. To find the references, look for the string implementation href in the file. Then change the value to the correct location for the current environment.

  2. Save the changes and close the file.

  3. Ensure that your custom configuration XML file is located in the directory you specified in step 2 of "Setting Up the oms-config.xml File".

  4. Deploy the oms.ear file that contains your oms-config.xml changes to your environment.

XML Catalog (Static Relative Location) Environment Configuration Method

You must perform the procedure below for each Design Studio environment.

  1. Edit your custom menu and action configuration XML file to ensure that it contains the correct location of any external files referenced in it. To find the references, look for the string implementation href in the file. Then change the value to the correct location for the current environment.

  2. Create or open a cartridge in Design Studio with the name and version that you configured in step 2 of "Setting Up the oms-config.xml File".

  3. Ensure that XML_CATALOG_SUPPORT is not set to disable for the cartridge. To check this, open the cartridge definition file, and click on the Cartridge Management Variables tab. By default, XML_CATALOG_SUPPORT is enabled, so if there is no entry in the Cartridge Management Variables table for that parameter, no change is needed. If there is an entry and it is set to disable, remove the entry and save the cartridge definition file.

  4. Copy your custom configuration XML file and any files that it references to the location you configured in step 2 of "Setting Up the oms-config.xml File". In the example, you would copy the files to the resources directory for your cartridge.

  5. Build and deploy the cartridge.

  6. Deploy the oms.ear file that contains your oms-config.xml changes to your environment.

XML Catalog (rewriteURI) Environment Configuration Method

You must perform the procedure below for each Design Studio environment. You must perform steps 4-7 whenever you change the location of the files.

  1. Edit your custom menu and action configuration XML file to ensure that it contains the correct location of any external files referenced in it. To find the references, look for the string implementation href in the file. Then change the value to the correct location for the current environment.

  2. Create or open a cartridge in Design Studio.

  3. Ensure that XML_CATALOG_SUPPORT is not set to disable for the cartridge. To check this, open the cartridge definition file, and click on the Cartridge Management Variables tab. By default, XML_CATALOG_SUPPORT is enabled, so if there is no entry in the Cartridge Management Variables table for that parameter, no change is needed. If there is an entry and it is set to disable, remove the entry and save the cartridge definition file.

  4. Copy your custom configuration XML file and any files that it references to a location of your choice, either inside or outside of the cartridge directory structure.

  5. Create a copy of the xmlCatalogCoreTemplate.xml file. It is located in the xmlCatalogs\core directory for your cartridge. You can name the copy anything you like as long as it is a different name from the original and it ends with .xml.

  6. In your new XML file, replace the commented text with a line indicating how you want to translate the URI into a file location. The new line should look something like this:

    <rewriteURI uriStartString=specified_namespace_string rewritePrefix="file-_location"/>
    

    where specified_namespace_string refers to the string you specified in step 2 of "Setting Up the oms-config.xml File" and file_location refers to the location where you copied your custom configuration files.

    For example, if you have copied the files to a location inside your cartridge directory structure, you would add a line similar to this:

    <rewriteURI uriStartString=http://example.org/somewhere rewritePrefix="osmmodel:///TestCartridge/1.0.0/resources"/>
    

    If you have copied the files to some location outside the Design Studio file structure, you would add a line similar to this:

    <rewriteURI uriStartString=http://example.org/somewhere rewritePrefix="file:///C:/LocalResourcesFolder/resources"/>
    
  7. Build and deploy the cartridge.

  8. Deploy the oms.ear file that contains your oms-config.xml changes to your environment.

Verifying the Changes

  1. If OSM was running when you made the changes to set up the environment, use the OSM Administrator application to refresh the metadata. This loads the latest configuration for the custom menu and actions.

  2. Log in to the Task Web client.

  3. In the Worklist or Query Results page, select any order and right-click.

    The context menu displays the new menu items, positioned at the bottom of the menu.