5 Customizing the Application

Oracle Communications MetaSolv Solution (MSS) provides three ways for the administrator to customize the application. You can:

  • Customize the desktop

  • Customize reports

  • Code stored procedures in user exits

    Note:

    Coding the user exits is a developer task and usually requires DBA assistance.

Customizing the Desktop

The main MetaSolv Solution desktop is a portal with one default portlet, the Welcome Page. Portlets are the building blocks of a portal. They are a convenient way to insert links to features or applications into the desktop.The user's MetaSolv Solution desktop can include a choice of portlets if you, the administrator, customize the default portlet and/or if you add portlets or permit users to customize their desktops.

In the MSS application, the administrator desktop displays a name for the System View and a pen icon. The pen icon appears only on the administrator view. Clicking the pen icon lets the administrator access windows to alter the default desktop.

Oracle ships pre-defined portlets, specified in metasolv-portlets.xreg registry file. If you allow it, users can select portlets for their desktops that are already defined or that have been defined by you. To allow users to customize their desktops, set the Allow users to customize My Desktop preference to Y.

Take note of the System View name and the pen icon at the top of the desktop. If you have not made any changes to the default portal or enabled users to customize their own desktops, the name area does not display System View or the pen icon.

To allow users to customize the default desktop, ensure the Allow users to customize My Desktop preference is set to Y.

The Allow users to customize My Desktop preference is located under Preferences > System Information.

To change the default desktop seen by users:

  1. Log on as the user ID specified in the gateway.ini DefaultPortalID parameter, usually known as the ASAP user

  2. Click the pen icon beside the System View.

  3. Follow directions in the online Help to make selections that set up the default desktop.

    Instructions for customizing the desktop appear in the online Help.

Configuring Portlets

The portlet registry file, my-portlets.xreg defines the portlets that you can select when customizing the desktop. If a portlet is to a third-party application and is located on another server, this file can define a logon alias so that users can access the other applications without logging on separately.

Metasolv-portlets.xreg is installed in /appserver/portal/conf, within the MetaSolv Solution root directory. It is a system file and should not be modified.

The My-portlets.xreg file starts with - <registry> and ends with </registry>. Each portlet is defined between <portlet-entry> and </portlet-entry>, as shown in the following sample. There can be more than one parameter per portlet.

The following is a sample of the My-portlets.xreg file:

<?xml version="1.0" encoding="UTF-8"?> 
- <registry>
- <portlet-entry name="MetaSolvHomePage" hidden="false" type="ref" parent="HTML" application="false">
- <meta-info>
  <title>Oracle</title> 
  <description>Oracle Home Page</description> 
  </meta-info>
  <classname>org.apache.jetspeed.portal.portlets.FileServerPortlet</classname> 
  <url cachedOnURL="true">http://www.metasolv.com</url> 
  <category group="Jetspeed">myGroup</category> 
  <parameter name="base" value="http://www.metasolv.com/" type="” hidden="false" cachedOnName="true" cachedOnValue="true" /> 
  </portlet-entry>
  </registry>

The following is a sample file with multiple portlets:

<?xml version="1.0" encoding="UTF-8"?>
<registry>
    <portlet-entry name="MetaSolvHomePage" hidden="false" type="ref"
        parent="HTML" application="false">
        <meta-info>
            <title>Oracle</title>
            <description>Oracle Home Page</description>
        </meta-info>

<classname>org.apache.jetspeed.portal.portlets.FileServerPortlet</classname>
        <url cachedOnURL="true">http://www.metasolv.com</url>
        <category group="Jetspeed">myGroup</category>
        <parameter name="base" value="http://www.metasolv.com/" type="" hidden="false"
            cachedOnName="true" cachedOnValue="true"/>
    </portlet-entry>
    <portlet-entry name="GooglePage" hidden="false" type="ref"
        parent="HTML" application="false">
        <meta-info>
            <title>Google</title>
            <description>Google Search Engine</description>
        </meta-info>
        <classname>org.apache.jetspeed.portal.portlets.FileServerPortlet</classname>
        <url cachedOnURL="true">http://www.google.com</url>
        <category group="Jetspeed">myGroup</category>
        <parameter name="base" value="http://www.google.com/" type="" hidden="false"
            cachedOnName="true" cachedOnValue="true"/>
    </portlet-entry>
</registry>

Table 5-1 lists the available parameters in the my-portlets.xreg file.

Table 5-1 Registry File Parameters

Registry File Parameter Parameter Description

portlet

(Optional) The parameter element has attributes and can be copied and edited for new elements.

Meta-Info

Meta-info has two elements that should be changed to match a custom portlet:

  • The title will be displayed in a portlet list as well as in the portlet title bar

  • The description will be displayed in the portlet list.

Sample:

<meta-info>
            <title>ABC</title>
            <description>ABC Home Page</description>
         </meta-info>

Classname

Classname is the portlet class which retrieves the content from the application, the value should be:

org.apache.jetspeed.portal.portlets.FileServerPortlet.
<classname>org.apache.jetspeed.portal.portlets.FileServerPortlet
         </classname>

Base parameter

The base parameter helps locate the portlet:

If the name is base, the application content's base is set to the URL specified in the value attribute. Some applications generate content which requires resources such as images. These resources may be referred to by the relative path to the root of the content. In this case, without the ”base" URL set correctly, the icons and images will not be displayed.

Most likely the base URL is first segment of the URL. For example, if the content is retrieved from

http://www.oracle.com/MSLV/CDA/General/Homepage/

the base is

http://www.oracle.com/.

If you are not sure about the base URL, ask the application Web Master. Following is a sample base parameter:

<parameter name="base" value="http://www.oracle.com/" type="”
               hidden="false" cachedOnName="true" cachedOnValue="true"/>

Parameters sent to the application

If the application requires a specific parameter (such as a stock symbol) you can define the parameter elements so that the parameter name and value attributes are sent to the application as the HTTP Request parameters. You must know what the application expects for the parameter name and define it identically and in the same case in the portlet-entry. For example:

<parameter name="symbol" value="MSLV" type=""
hidden="false" cachedOnName="true" cachedOnValue="true"/>

Note that if the hidden attribute is set to true, the users will not see this parameter in the portlet customization. If it is set to false, this parameter can be customized.

URL

The URL element specifies the location of the application content. The cachedOnURL attribute should be true. For example:

<url cachedOnURL="true">http://www.oracle.com</url>

Adding Portlets

When portlets are enabled at startup of the Oracle WebLogic server, MetaSolv Solution reads all xreg files.

To add portlets to the list of available portlets:

  1. The first time you add portlets, copy the sample file, $MSLV_HOME/appserver/portal/examples/my-portlets.xreg and use it to create another portlet registry file with a unique name in the $MSLV_HOME/appserver/portal/conf. Make sure the file has an xreg extension.

  2. Change only the name attribute with a unique portlet name within a <portlet-entry></portlet-entry>. The portlet-entry tag itself has name, hidden, type, parent, and application attributes.

  3. Under the portlet-entry, specify meta-info, classname, parameter (optional), URL, and category as described in Table 5-1, "Registry File Parameters".

  4. After a custom portlet is added into the registry, restart the Oracle WebLogic server or redeploy the application (nur.ear) to reload the portlet registry.

Managing Logons within Portlets

When you authenticate a user via the portlet, the user can access an application within the same Oracle WebLogic server or other Oracle WebLogic servers in the same cluster without logging on separately. However if the application is third party software, or if the application is not in the cluster, logon information must be defined in the portlet if the application requires authentication. There are three options. See the following for sections details.

Defining aliases

You can define the $PRINCIPAL and $PASSWORD aliases in the portlet-entry's URL as HTTP request parameters, as in this example:

<url cachedOnURL="true">https://xyz-site/function?
username=$PRINCIPAL&amp;password=$PASSWORD</url>

Note:

&amp; is used to separate the parameters. You cannot use & directly since it is a special character in HTML, thus you must use the escape sequence &amp;. Be sure to include the semi-colon.

In the above example, the ? indicates there are appending parameters. The username and password are the parameter names. Ask the Web-Master for the real parameter names for the username and password. The $PRINCIPAL and $PASSWORD aliases are expanded with the real user name and password by the portlet and will be the same one with which the user logged on. Use HTTPS so that the username and password are encrypted.

The advantage of this mechanism is that logging on is automatic. The user does not need to be prompted to enter a username and password.

The limitations of this mechanism are:

  • The username and password must be the same on both the MetaSolv Solution portlet and the third party application.

  • If the third party application generated content contains hyperlinks, the username and password must be encoded in the links by the third party application.

Defining name and password as portlet-entry parameters

You can define the username and password as portlet-entry parameters. These parameters can be customized by users and are sent to the third party application as HTTP request parameters. The application must be coded to extract the username and password parameters from the HTTP request. After the user is authenticated, the application returns the content. Using HTTPS in the URL parameter encrypts the username and password.

The name is case-sensitive. You must know what the application expects for the parameter name and define it exactly the same in the portlet-entry. For example:

<parameter name="username" value="bsmith" type=""
hidden="false" cachedOnName="true" cachedOnValue="true"/>
<parameter name="password" value="mypassword" type=""
hidden="false" cachedOnName="true" cachedOnValue="true"/>

Note:

If a hidden attribute is set to true, then the users will not see this parameter in the portlet customization. If it is set to false, then this parameter can be customized.

The advantages of this mechanism are:

  • Automatic logon: The user does not need to be prompted to enter username and password.

  • The username and password do not need to be the same on both MetaSolv Solution portlet and the third party application.

The limitations of this mechanism are:

  • The users need to manually enter the username and password in portlet customization.

  • If the third party application generated content contains hyperlinks, the username and password must be encoded in the links by the third party application.

Prompting for the username and password

Instead of sending the username and password embedded in the HTTP request, you can allow the third party application to prompt for the username and password. After the user submits the logon information, a new window displays the third party application content.

The advantages of this mechanism are:

  • The third party application does not need to be coded to extract the username and password parameters from the URL.

  • The third party application does not need to encode the username and password in the links in the generated content.

The limitation of this mechanism:

  • There is no automatic logon.

Restart the Oracle WebLogic server after modifying the portlet registry file.

Third Party Portlet Accesses MetaSolv Solution Applications

MetaSolv Solution Struts Framework extracts the username and password from the HTTP request and performs the authentication. Once the user is authenticated, a session is established, and the following requests from the same user do not need to be authenticated until the user logs off.

Following is the list of HTTP request case-sensitive parameters that can be sent to MetaSolv Solution application:

  • UserID - the value of this parameter is the username.

  • Password - the value if this parameter is the password.

  • TimeZoneID - the time zone id of the user, if not specified the current MetaSolv Solution Portal time zone id is used.

HTTPS is recommended to encode the user name and password, for example:

<https://wsplwss01:7002/main/getMyTask.do?UserID=test&Password=test>

The session is terminated when it is expired (by default 15 minutes), or when the user logs off:

<http://wsplwss01:8001/main/logoff.do>

Customizing the Navbar

The Navbar tab on the GUI navigation bar contains the standard navigation for MetaSolv Solution. Use the My Navbar tab on the navigation bar to display a custom configuration of groups and links. After you customize the My Navbar tab, it becomes the default navigation for all users. You can select the Navbar tab on the navigation bar to return to the original navigation.

To allow users to customize the default navigation bare, ensure the Allow users to customize My Desktop preference is set to Y.

To customize My Navbar:

  1. Click My Desktop at the top of the navigation bar.

  2. Select Options > Customize Navigation Bar from the menu.

  3. To modify the My Navbar tab on the navigation bar, do one of the following:

    • Click the Add a new group link.

      Enter the group name, select each link you want to add, and click the right arrow button to add.

      To add external links to documents, Web pages, or applications, click the Add your own links link at the bottom of the window. After entering the link name and file location, you can click the Test Link button before adding it to the list.

    • Click the Edit a group link.

    • Click the Change the order of groups link.

  4. Complete the necessary windows, following instructions in the online Help.

To delete all My Navbar changes:

  1. Display My Navbar.

  2. Open the Options menu.

  3. Click Customize My Navigation Bar.

  4. Click the Reset My Navbar button.

Producing Custom Reports

MetaSolv Solution provides preloaded GUI reports through the reporting, trouble management, and security functions. The reporting function provides a variety of reports that can be selected. Instructions for producing these reports appear in the online Help.

When MetaSolv Solution is installed, the installation process deploys a PowerBuilder file named I_rpt.pbl, a file that contains predefined MetaSolv Solution reports in the form of datawindows.

You can also create custom reports that you add to the Selected Report list.To create customized reports for MetaSolv Solution, you must purchase and install PowerBuilder or InfoMaker and follow directions in that documentation to create a report and copy it to the reporting pbl.

For information on using PowerBuilder or InfoMaker, investigate the Sybase Web site at:

http://go.sap.com/index.html

Creating a Customized Report

To create a customized report and add it to MetaSolv Solution:

  1. Create the report using PowerBuilder or InfoMaker.

    See the third-party documentation for instructions. Use PowerBuilder to copy the report datawindow to I_rpt.pbl on the machine where Tbs.exe runs.

  2. Log in to MetaSolv Solution.

  3. Click the Reporting group.

  4. Click Register Reports and follow directions in the Help to add a new report.

Once registered, the customized report can be selected from the Selected Report drop-down on the Reports window. See the online Help topic about generating a custom report for instructions.

Retaining Customized Reports After an Upgrade

When a new release is installed, the installation process deploys a new copy of I_rpt.pbl. Pre-existing customized reports must then be manually added to the new I_rpt.pbl using PowerBuilder.

To retain customized reports:

  1. Copy the existing copy of I_rpt.pbl with a different name and save it.

  2. Open the copy of I_rpt.pbl in PowerBuilder.

  3. Copy the datawindows for pre-existing custom reports to the new I_rpt.pbl.

  4. Manually distribute the updated I_rpt.pbl to all client machines.

If you select a report, you may get the following error message:

The selected report does not have a datawindow object in I_RPT.BPL.

This error message indicates that the datawindow has not been added to the I_rpt.pbl file on your machine.

If a data window name for a custom report cannot be found in the drop-down after an upgrade:

  1. Unregister the report through the application by deleting the row in the Register Reports window.

  2. Register the report again in the new version of MetaSolv Solution.

Using Stored Procedure Exits

MetaSolv Solution provides user exits for the purpose of making database calls. The exits are empty shells of stored procedures that are already part of the application code. To code these exits, you should be familiar with PL/SQL. Because these are empty shells, you are responsible for any impact a user exit has on performance or data. You must optimize your company's code.

Note:

Oracle Global Customer Support (GCS) supports user exits as they are written within the delivered code. GCS does not support any customer-developed code that is stored within these shells nor do we support any residual affects to our delivered code or to any data stored in the database caused by customer-derived code.

With these exits, you can have MetaSolv Solution perform tasks that are specific to your business needs, such as:

  • Performing custom validation and pre-PSR validation

  • Defining dependencies

  • Changing optional fields to required

  • Defining default fields, such as a Web host user ID

  • Generating free-format circuit IDs

  • Validate e-mail, ID, and password entries on e-mail service items and Web host items

You cannot use these exits to perform other functions or to call other applications.

Retaining User Exits After an Upgrade

When a new release is installed, the installation process deploys new stored procedures. Pre-existing customized stored procedures (exits) must be saved before the service pack or new release is installed.

To retain existing user exits:

  1. Copy the existing stored procedures with different names.

  2. Install the service pack or new release.

  3. Copy the customized user exits files back to the updated version of the application.

Coding User Exits

These exits are stored in files in the procs directory. The procs directory is installed at the location where the database installer was run. Contact a DBA to find the location.

The following sections provide information for each user exit, including:

  • Description

  • Exit name

  • File name

To add code to a stored procedure exit:

  1. Locate the appropriate file for the exit you want to use.

  2. Open the file with Notepad or other basic text editor.

  3. Add lines of SQL code to define the task you want the application to perform.

  4. Save the file.

  5. Run the file, so the proc with the new code can exist on the database.

Generate a Circuit ID

You can add code to this exit to set the format for a custom circuit ID. The exit is only available for OTF and OTS circuit format types. To call this procedure, the user must first set the Customer Generated Freeformat Circuit ID preference to Y. After setting the preference to Y, the user can access the Connection Identification Maintenance window for a circuit and see an option called Generate Circuit ID.

Table 5-2 describes the circuit ID exit.

Table 5-2 Circuit ID Exit

Identifier Description

GUI location

Connection Identification Maintenance window

Exit name

pkg_generate_freeformat_ecckt.sp_generate_ecckt

File name

paecckt.sql

Generate a Custom Customer Account Number

You can add code to this exit to generate a custom customer account number when creating or selecting a customer for a new Product Service Request. If the user is in Customer Maintenance, the procedure is called by clicking the Apply button or moving from the General tab. If the user is creating the customer directly from the PSR, the procedure is called by clicking OK after entering all of the customer information or selecting an existing customer.

Table 5-3 describes the customer account number exit.

Table 5-3 Customer Account Number Exit

Identifier Description

GUI location

Customer Account Maintenance window

Exit name

sp_PSR_cust_acct_number

File name

custacct.sql

Perform Custom Validation on Network Locations

You can add code to this exit to create custom validations for network locations. This procedure functions when the user clicks the OK button on the Network Location window for a new or existing network location.

Table 5-4 describes the custom validation on network locations exit.

Table 5-4 Custom Validation on Network Locations Exit

Identifier Description

GUI location

Network Location New window

Exit name

sp_NL_custom_validation

File name

nlcustom.sql

PSR Custom Pre-Validation

You can add code to this exit to automatically pre-validate a PSR order. This stored procedure exit is called when validating or finishing a PSR order and is called prior to MetaSolv Solution's validation and prior to the other PSR custom validation user exit discussed in "Perform Custom Validation on a PSR Order".

Table 5-5 describes the PSR custom pre-validation exit.

Table 5-5 PSR Custom Pre-Validation Exit

Identifier Description

GUI location

PSR order

Exit name

Sp_psr_custom_pre_validation

File name

soppreval.sql

Perform Custom Validation on a PSR Order

You can add code to this exit to perform custom validation on a PSR order. To call this procedure, the user validates or finishes a PSR order.

Table 5-6 describes the PSR custom validation exit.

Table 5-6 PSR Custom Validation Exit

Identifier Description

GUI location

PSR Order

Exit name

Sp_psr_custom_validation

File name

socustom.sql

Perform Custom Validation at Task Completion

You can add code to this exit to perform a custom validation at task completion. This stored procedure is called when a user completes any Work Management task, if the Perform Custom Validation at Task Completion preference is set to Y.

Table 5-7 describes the custom validation at task completion exit.

Table 5-7 Custom Validation at Task Completion Exit

Identifier Description

GUI location

Task Completion Maintenance window

Exit name

sp_wm_custom_validation

File name

wmcustom.sql

Populate the Internet Dial Up User ID

You can add code to this exit to automatically populate the Internet Dial Up user ID. This stored procedure is called when a user first accesses the Dial Up Info tab on a PSR, including an Internet Dial Up service item.

Table 5-8 describes the Internet Dial Up user ID exit.

Table 5-8 Internet Dial Up User ID Exit

Identifier Description

GUI location

Dial Up Info tab

Exit name

pkg_psr_custom_keys.sp_custom_dialup_userid

File name

papsrcky.sql

Populate the Internet Dial Up Password

You can add code to this exit to automatically populate the Internet Dial Up password. This stored procedure is called when a user first accesses the Dial Up Info tab on a PSR, including an Internet Dial Up service item.

Table 5-9 describes the Internet Dial Up password exit.

Table 5-9 Internet Dial Up Password Exit

Identifier Description

GUI location

Dial Up Info tab

Exit name

pkg_psr_custom_keys.sp_custom_dialup_password

File name

papsrcky.sql

Populate the PSR Email Password

You can add code to this exit to automatically populate the PSR email password. This stored procedure is called when a user first accesses an Email item's Email Info tab on a PSR order.

Table 5-10 describes the PSR email password exit.

Table 5-10 PSR Email Password Exit

Identifier Description

GUI location

Email Info tab

Exit name

pkg_psr_custom_keys.sp_custom_email_password

File name

papsrcky.sql

Populate the Web Hosting User ID

You can add code to this exit to automatically populate the Web Hosting user ID. This stored procedure is called when a user first accesses the Web Host Info tab on a PSR for a Web Hosting item.

Table 5-11 describes the Web Hosting user ID exit.

Table 5-11 Web Hosting User ID Exit

Identifier Description

GUI location

Web Host Info tab

Exit name

pkg_psr_custom_keys.sp_custom_webhost_userid

File name

papsrcky.sql

Populate the Web Hosting Password

You can add code to this exit to automatically populate the Web Hosting password. This stored procedure is called when a user first accesses the Web Host Info tab on a PSR for a Web Hosting item.

Table 5-12 describes the web hosting password exit.

Table 5-12 Web Hosting Password Exit

Identifier Description

GUI location

Web Host Info tab

Exit name

pkg_psr_custom_keys.sp_custom_webhost_password

File name

papsrcky.sql

Populate the URL

You can add code to this exit to automatically populate the URL on the Dial Up Info tab. This stored procedure exit is called when a user first accesses the Dial Up Info tab on a PSR for an Internet Dial Up service item.

Table 5-13 describes the Dial Up URL exit.

Table 5-13 Dial Up URL Exit

Identifier Description

GUI location

Dial Up Info tab

Exit name

pkg_psr_custom_keys.sp_custom_url

File name

papsrcky.sql

Validate an Email Address

You can add code to this exit to automatically validate the email address entered on an Email service item email Info tab. This stored procedure exit is called on a save, when the user tries to move to another service item or when the user validates.

Table 5-14 describes the email address validation exit.

Table 5-14 Email Address Validation Exit

Identifier Description

GUI location

Email tab of email service item

Exit name

pkg_psr_custom_keys.sp_custom_email_validation

File name

papsrsky.sql

Validate a User ID

You can add code to this exit to automatically validate the user ID entered in the GUI locations listed below. This stored procedure exit is called on a save, when the user tries to move to another service item or when the user validates.

Table 5-15 describes the user ID validation exit.

Table 5-15 User ID Validation Exit

Identifier Description

GUI location

  • Dial up Info tab

  • Web Host Info tab

Exit name

pkg_psr_custom_keys.sp_custom_userid_ validation

File name

papsrcky.sql

Validate a Password

You can add code to this exit to automatically validate the password entered the GUI locations listed in the table below. This stored procedure exit is called on a save, when the user tries to move to another service item or when the user clicks validate.

Table 5-16 describes the password validation exit.

Table 5-16 Password Validation Exit

Identifier Description

GUI location

  • Email tab of Email Service Item,

  • Dial up tab of Dial up service item

  • Web Host tab of Web Host service item

Exit name

pkg_psr_custom_keys.sp_custom_password_validation

File name

papsrcky.sql

Generate an MSAG Validation Audit Trail

You can add code to this exit to generate an MSAG validation audit trail. The stored procedure is called from the End User Location Maintenance window, after the MSAG validation occurs.

Table 5-17 describes the MSAG validation audit trail exit.

Table 5-17 MSAG Validation Audit Trail Exit

Identifier Description

GUI location

End User Location Maintenance window

Exit name

sp_psr_msag_custom_validation

File name

somsagcustom.sql