31 Using Customer Center SDK

This chapter provides information on using the Oracle Communications Billing and Revenue Management (BRM) Customer Center Software Development Kit (SDK) for customizing the Customer Center and Self-Care Manager client applications. While Customer Center and Self-Care Manager share many of the controllers for communicating with BRM, their client interfaces differ. See "Customizing the Customer Center Interface" and "Customizing the Self-Care Manager Interface".

Note:

To install Customer Center SDK, see "Installing Customer Center SDK on Windows" in BRM Installation Guide.

About Customer Center SDK

Customer Center SDK provides the framework and toolkit you need to customize and configure the default implementations of Customer Center and Self-Care Manager.

About Using Customer Center SDK to Customize Customer Center

Customer Center SDK allows you to modify the appearance and behavior of Customer Center to meet your business needs. You make these changes by using the customization APIs available for each screen of Customer Center.

Customer Center SDK includes a client application called Configurator that provides a graphical user interface for making modifications and additions to the default Customer Center properties and resources. Configurator allows you to:

• Change Customer Center tab order or tab contents

• Remove certain Customer Center fields

• Change Customer Center behavior

• Change the fields displayed in account search results

For information on using Configurator to make these changes to Customer Center, see "Customizing the Customer Center Interface".

Important:

Because of interdependencies between fields that reside on multiple panels, certain fields cannot be removed from the Customer Center interface. Additionally, existing fields cannot be rearranged.

The SDK also includes scripts, customized properties files, source code examples, and a utility for exploring and copying field definitions that you can use for extending or customizing Customer Center functionality.

For customizing or modifying the Customer Center Help, the SDK provides the online help in a compressed file. Scripts are provided for unpacking the file and creating a new custom help file for deployment from your Customer Center deployment servers.

For information on deploying Customer Center changes you make using Customer Center SDK, see "About Compiling and Packaging Your Customizations".

About Using Customer Center SDK to Customize Self-Care Manager

Self-Care Manager allows your customers to log into their accounts and view their account and product information by using a Web browser. Customer Center SDK allows you to modify the appearance and behavior of Self-Care Manager to meet your business needs.

Customer Center SDK includes the following components for customizing Self-Care Manager:

• HTML code you can edit to change the appearance of the web pages.

• Java Server pages (JSPs) for changing the layout of the Self-Care Manager interface, removing elements included in the default JSPs, or using a different set of components.

• Examples of modified JSPs and custom controllers for extending Self-Care Manager functionality.

• Scripts that build and package a custom Self-Care Manager Web Application Archive (WAR) file for deploying your customized files. See "Modifying the Self-Care Manager WAR File" in BRM Managing Customers for information about deploying an updated WAR file.

Contents of Customer Center SDK

Customer Center SDK includes these components.

For modifying Customer Center and Self-Care Manager:

• buildall, a batch file for building your customized Customer Center and Self-Care Manager code. See "About Compiling and Packaging Your Customizations".

• "Customer Care API Reference", a set of JavaDocs describing the Customer Center SDK classes.

For modifying Customer Center only:

• Configurator, a graphical utility for implementing many common GUI modifications

• Scripts, for testing your code.

Customer Care API Reference

See Customer Care API reference for JavaDocs describing Customer Care classes.

Customer Care API reference is also available in your CCSDK_Home\CustomerCareSDK\docs directory. To view the documentation, use a Web browser to open the index.html file in this directory.

Coding Your Customizations

To design and code your customizations, see "Customizing the Customer Center Interface" or "Customizing the Self-Care Manager Interface".

About Compiling and Packaging Your Customizations

You compile your customizations to Customer Center and Self-Care Manager by using the buildall script in the CCSDK_Home\CustomerCareSDK directory, where CCSDK_Home is the directory in which you installed Customer Center SDK components. This script calls other scripts to accomplish the following tasks:

• For Customer Center:

  • Compiles any Java source code files encountered in the CCSDK_Home\CustomerCareSDK\CustCntr\custom directory.

  • Repackages the newly compiled class files and the WizardCustomizations and Customized properties files into a CCSDK_Home\CustomerCareSDK\CustCntr\custom\ccCustom.jar file.

  • Signs the new ccCustom.jar file with a Java Security Certificate.

• For Self-Care Manager:

  • Compiles any Java source code files encountered in the subdirectories under the CCSDK_Home\CustomerCareSDK\WebKit\custom directory.

  • Repackages the newly compiled class files into a webkit_en.war file.

  • Builds a new CCSDK_Home\CustomerCareSDK\WebKit\custom\webkit_en.war file.

Figure 31-1 and Figure 31-2 show the relationships between the buildall script and the scripts it calls to accomplish these tasks:

• For building a ccCustom.jar file for Customer Center:

Figure 31-1 Building Customer Center

Description of ''Figure 31-1 Building Customer Center''

• For building a webkit_en.war file for Self-Care Manager:

Figure 31-2 Building Self-Care Manager

Description of ''Figure 31-2 Building Self-Care Manager''

This script calls the following scripts to process your files:

• custom compiles any .java files found in the CustCntr\custom or WebKit\custom directories.

• signjar (Customer Center only) signs the new ccCustom.jar distribution file with a security certificate, either a valid one obtained from an authorized provider or a self-signed certificate created with the makecertificate script. Before running the buildAll script, be sure to edit signjar to add values to the KEYPASSWORD and STOREPASSWORD entries.

• common compiles any.java files for controllers used by both Customer Center and Self-Care Manager found in the common_files directory.

  Important:

  Do not run the custom, signjar, or common scripts directly. They are designed to be called by buildAll only.

Coding, Building, and Deploying Customizations

To code, build, and deploy your customizations, see:

• For Customer Center, "Building Your Customer Center Customizations".

• For Self-Care Manager, "Building the Self-Care Manager Components".

  Note:

  To develop and deploy customized Customer Center Help, see "Customizing the Customer Center Help System"

Syntax for the buildAll Script

The buildAll script is used to build the customized jar files for your Customer Center and Self-Care Manager customizations.

This section describes the syntax for the buildAll script. For general information on how to use the buildAll script for the client applications, see:

• For Customer Center, "Building Your Customer Center Customizations"

• For Self-Care Manager, "Building the Self-Care Manager Components"

Syntax

buildAll CustCntr|WebKit [clean]

File Location

CCSDK_Home\CustomerCareSDK

Parameters

Table 31-1 lists the parameters for the buildAll script.

Table 31-1 buildAll Script Parameters

Parameter	Description
CustCntr	Use this parameter to compile any new source code you put in the CCSDK_Home\CustomerCareSDK\common_files and CustCntr\custom directories. The ccCustoml.jar file is created and signed.
WebKit	Use this parameter to compile any new source code you put in the CCSDK_Home\CustomerCareSDK\common_files and WebKit\custom directories. The webkit_en.war file is created.
clean	Use the clean parameter with the CustCntr or WebKit parameters to verify that class files left from a previous build are removed before running buildAll again to rebuild the custom jar or war file. You must specify the CustCntr or WebKit parameters, not both, when you use the clean parameter.

Testing Your Customizations for Customer Center

To test the customizations you made to Customer Center:

1. Run the runCustomerCenter script, in the CCSDK_Home\CustomerCareSDK\CustCntr\bin directory.

2. When the Login dialog box appears, enter your login information, and then click OK.

A local version of the Customer Center application starts. Any customizations you made are represented in this local version of Customer Center.

Understanding the BRM Business Application SDK Framework

Customer Center and Self-Care Manager use the Business Application SDK (BAS) framework. The BAS framework supports the construction of a set of distributed objects and mutually independent BRM Infranet-aware (PIA) components.

The Model-View-Controller Architecture

The BRM business applications framework is based on the model-view-controller (MVC) paradigm. In this paradigm, a component's control logic is separated from its display:

• The model component is the data. BRM data and BRM data types exist only in the controllers.

• The view component is the display of the data in the user interface. The view component handles only the Java data.

• The controller component is the logic on the server that determines the behavior of the data and how the data is displayed. The controllers convert the BRM data into Java data such as Vector, int, Date, and String.

In Customer Center and Self-Care Manager, the controller and view components are combined.

Figure 31-3 shows the Customer Care architecture:

Figure 31-3 Customer Care Architecture

Description of ''Figure 31-3 Customer Care Architecture''

How the Controllers Work

This section describes the basic controller process:

1. When users interact with a component, the component calls setModelHandle, which sets the appropriate property for the field and sends the model handle to the controller.

2. The component calls the controller's update method.

3. The controller communicates with BRM by calling the necessary opcodes.

4. The opcodes get the fields specified in the field specification or they get data after performing calculations or other functions, depending on the component.

Example Data Flow between a Simple Field and BRM

This example shows the data flow between the view component of a simple text field in the Account Maintenance panel, its controller, and BRM:

1. An external action, such as selecting an account in the Search Results panel, initiates a call to setModelHandle on a text field.

2. The text field view component calls its controller to get the data that corresponds to its displayFieldDescription.

3. The controller communicates with BRM by calling opcodes or reading objects.

4. The controller reads the /account object in the database and gets the fields specified by the display field specification.

5. The controller computes a new value and saves it in a property, for example, mField=val.

6. The view component calls a get method, for example, getField(), to get the previous property, and then sets this value in its display with setText(getField()).

About Field Components

Field components have model handles and the Customer Center SDK components contain references to field subclasses in the BRM database. These components have several properties, for example:

• Model field description

  Specifies the data that a field contains. For example, the first name field has this specification for model field: FldNameInfo[1].FldFirstName.

• Display field description

  Specifies the data to display. For example, the read-only field of an account object might have this specification for the display field: FldNameInfo[1].FldFirstName,FldNameInfo[1].FldLastName, FldAccountNo.

• Display field format

  Specifies the display format for the data specified in the display field. An /account object might have this specification for the display field format: {0}{1} - {2} to display the account information in the "First name Last name - Account number" format or {1}{0} - {2} to display "Last name First name - Account number" format. The field numbers, such as {0}, {1}, correspond to the order in which they are specified in the display field specification.

Every field component must have a specification for its modelFieldDescription, its displayFieldDescription, or both. The properties of the field depend on the type of the field. For example, a read-only field does not have a modelFieldDescription property, but it does have displayFieldDescription and displayFieldFormat properties.

Note:

Field component names follow the Java class-naming conventions and use mixed case without the underscores. The Java field classes in the Java Portal Communication Module (PCM) package included in Customer Center SDK use the C #define name without the PIN_ prefix. For example, PIN_FLD_NAME_INFO in C becomes FldNameInfo in Java. See "Creating Client Applications by Using Java PCM" for information about Java PCM. See Customer Care API reference for the com.portal.pcm.fields package for information about the supported field subclasses.

Displaying Versus Saving Data in Fields

You use fields in a panel to display data as well as to allow users to change data. When users change data, their changes must be saved in the database. To implement reading from and writing to the object field in the database, you need to understand the read and write functions in BRM.

For information on BRM read and write fields functions, see "Base Opcodes".

For most fields that you create, you use the modelFieldDescription property to display and save changes to the data. For example, to display as well as save changes to the first name in the FldNameinfo field for the billing contact, you can use the following property for both modelFieldDescription and displayFieldDescription:

FldNameinfo[1].FldFirstName 
  

However, not all fields have the same string for their model and display field descriptors.

In cases where reading the data is different from writing the data, such as the FldPayinfo data:

• For reading the data, set the description in displayFieldDescription.

• For writing the data, set the description in modelFieldDescription.

For example, use the following displayFieldDescription to read the credit card number field:

FldPayinfoObj.FldccInfo[0].FldDebitNum 
  

And use the following modelFieldDescription to write the credit card number field:

FldPayinfo[1].FldInheritedInfo[0].FldccInfo[0].FldDebitNum 
  

See Customer Care API reference for PCreditCardPanel.java for examples of setting the description in this manner.

BRM Infranet-aware (PIA) components:

• Are Swing compatible.

• Have references to specific storable class fields.

• Contain APIs that allow you to map them to specific fields in BRM storable classes, such as account.

• Have both client and server implementations, which allow individual components to encapsulate data retrieval and user interface (UI) display.

Display Fields and Controllers

You can use properties, such as a modelFieldDescription and a displayFieldDescription, when there is a one-to-one correspondence between the fields in the Customer Center interface and the fields in the BRM object. For example, fields such as first name and last name have fields of type String in the /account object that map exactly to the display. Therefore, you can specify their data by specifying values for the modelFieldDescription and displayFieldDescription properties in a graphical IDE, such as JBuilder.

To display fields that do not have one-to-one mapping in the object, you need to extend an existing controller or create a new one. For example, the currency field is an integer type in the /account object. To display it as a string such as "US Dollar" in the user interface, you need to write a controller that:

• Takes the integer.

• Looks it up in the balance element ID (BEID) table.

• Gets the appropriate string description or name of the currency represented by the integer.

You can write controllers that perform any number of functions. For example, a controller can:

• Perform simple tasks, such as simple translations. For example, you can map an integer type to a string description and send it to the view component.

• Call opcodes and process information.

  • For example, to display the available payment methods, you can write a controller that calls the appropriate opcode, retrieves the data in a vector, and sends the vector to the view component.

  • You can initialize data (flists) for payment information.

    Important:

    • If you create a new Infranet-aware field, you must create a controller for the field.

    • (Self-Care Manager only) If you add a field component to a JSP that has a controller, you might need to add code to the JSP controller for any special processing of the new field. This code is necessary, for example, when you add custom fields to BRM and use Self-Care Manager to access them. For example, com.portal.app.comp.PIAPhoneTableBeanImpl handles the special processing for the phone fields for account creation. If you create a new Infranet-aware field, you need to create a controller for the field.

About PModelHandle

A PModelHandle is an object that passes a reference to a BRM data object. Because the view code does not have access to the PCM library, the BAS API creates this object for client applications to use.

The data referenced by aPModelHandle is converted from its specified modelFieldDescription to an flist or a storable class, such as /account, for the BRM opcodes to use.

When data is returned from BRM, the BAS API converts it into the format specified by the displayFieldDescription for that object and the results are displayed in the associated Customer Center field.

About Lightweight Components (Self-Care Manager Only)

Lightweight components such as text field components are only view components. They are used for storing and displaying data. They do not contain control logic. The encapsulating parent component or the page controller handles the lightweight components. They do not each need a controller.

Use lightweight components to map a UI field to a specific field in a BRM storable class, such as /account. The lightweight component used in Self-Care Manager is PLightComponentHelper. It is a wrapper for a field component (PFieldBean), which allows data to be retrieved from and passed to BRM.

For example, the credit card number UI field does not have a controller because it does not need information from the database; the "Choose service" UI field needs a controller to call the opcode to retrieve the list of available plans. So the credit card number is created as a lightweight component, but "Choose service" is not.

Source Code Examples

Customer Center SDK provides scripts and applications for customizing Customer Center and Self-Care Manager. When you use Configurator or make entries or changes to the editable properties files, the buildAll script creates a new custom distribution file you copy to the appropriate directory to deploy your changes in a production environment. For Customer Center, the script creates a new jar file signed with a digital certificate. For Self-Care Manager, the script creates a new war file.

Source code examples are provided with Customer Center SDK to show how to use some of the more useful public API available to you.

For more information, see "Customer Center Customization Examples" and "Self-Care Manager Customization Examples".