Using Custom Menu Items and Actions

5 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. Refresh the server cache in the Administration area of the OSM Order Management web client (or an Ant task in the Cartridge Development Kit) to trigger a reload of the configuration file.

The name and location of the custom menu action file are configurable parameters. For traditional OSM, these are available in the oms-config.xml file. In OSM cloud native, these can be set in the specification files. See the "Configuring Parameters" section in "Chapter 6 Creating Your Own OSM Cloud Native" Instance of OSM Cloud Native Deployment Guide for details on working with osm-config parameters in cloud native.

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

About the Model Definition

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

Action Definition

Table 5-1 lists the action elements.

Table 5-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 5-2 shows the method calls that can be made on the orderContext and order objects.

Table 5-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 5-3 shows the elements of the menu item definition.

Table 5-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	Set to true(), true, yes, or y (case-insensitive) to enable the menu item, or set to anything else to disable it.
visible	Set to true(), true, yes, or y (case-insensitive) to make the menu item visible, or set to anything else to make the menu item invisible.
displayStyle	The display style of the menu item on the context menu, either ICON, or TEXT, or both (ICON TEXT). 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:

File system path method: This is the simplest configuration method for a single environment. It does not require any cartridges for its implementation. However, it does require you to unpack, repack, and redeploy the oms.ear file for each environment with a different file location and every time the file location changes.
XML Catalog (Static Relative Location) method: This method uses the XML Catalog function in Oracle Communications Design Studio. It allows you to deploy the resources with a cartridge, and configure a static location for the source files based on their location in the Design Studio files hierarchy. This means that the files can be deployed from Studio to environments in different locations, and having different file structures, without needing any further manual intervention.
XML Catalog (rewriteURI) method: This method uses the XML Catalog function in Design Studio. It provides a mechanism for you to define the location of the files dynamically, either to an absolute file location or to a location relative to the current Design Studio environment. You can then change the location for the files without having to edit the oms-config.xml file. This could be especially useful while you are developing or unit testing the configuration, as you could define a local directory for the files and change them without having to redeploy the cartridge after each change.

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

Setting Up the oms-config.xml File (Traditional OSM Only)

All three methods of environment configuration require that you set up the oms-config.xml 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.

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>

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).

Working with oms-config Parameters in OSM Cloud Native

In OSM cloud native, all oms-config parameters can be updated in the specification files. The parameter name and value can be set in either the shape, instance, or project specification files. For more details, see OSM Cloud Native Deployment Guide.

File System Path Environment Configuration Method

You must perform the procedure below for each server environment.

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.
Save the changes and close the file.
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 (Traditional OSM Only)."
Do one of the following:
- For traditional OSM, deploy the oms.ear file that contains your oms-config.xml changes to the environment.
- For OSM cloud native, create or update your OSM instance with the new oms config parameters. See the "Configuring Parameters" section in "Chapter 6 Creating Your Own OSM Cloud Native Instance" of OSM Cloud Native Deployment Guide.

XML Catalog (Static Relative Location) Environment Configuration Method

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

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.
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 (Traditional OSM Only)."
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.
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 (Traditional OSM Only)." In the example, you would copy the files to the resources directory for your cartridge.
Build and deploy the cartridge.
Do one of the following:
- For traditional OSM, deploy the oms.ear file that contains your oms-config.xml changes to the environment.
- For OSM cloud native, create or update your OSM instance with the new oms config parameters. See the "Configuring Parameters" section in "Chapter 6 Creating Your Own OSM Cloud Native Instance" of OSM Cloud Native Deployment Guide.

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.

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.
Create or open a cartridge in Design Studio.
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.
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.
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.
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 (Traditional OSM Only)" 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"/>
```
Note:
File re-write is not supported in OSM cloud native.
Build and deploy the cartridge.
Do one of the following:
- For traditional OSM, deploy the oms.ear file that contains your oms-config.xml changes to the environment.
- For OSM cloud native, create or update your OSM instance with the new oms config parameters. See the "Configuring Parameters" section in "Chapter 6 Creating Your Own OSM Cloud Native Instance" of OSM Cloud Native Deployment Guide.

Verifying the Changes

If OSM was running when you made the changes to set up the environment, refresh the server cache in the Administration area of the OSM Order Management web client to refresh the metadata. This loads the latest configuration for the custom menu and actions.
Log in to the Task web client.
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.