This chapter provides several examples for customizing the address book service in Oracle Communications Convergence.
To perform any Convergence customization, you should have expert knowledge in dojo and knowledge of UI customization. For more information on general Convergence customization, see "Technical Overview".
Nearly all customization examples require the same setup and preparation.
You start by verifying that the c11n_Home directory exists. If it does not exist, create it.
See "Customization Directory Structure" for more information.
Next, you verify that customization is enabled in Convergence. If customization is disabled, enable it.
See "Enabling Customization in the Convergence Server" for more information.
When you have completed your customization, you must restart the Oracle certified application server for Convergence.
See Convergence System Administrator's Guide for more information.
By default, when a user selects the corporate address book, the Corporate Directory tab appears in the Convergence UI.
If the address book service is provided by Convergence, you can customize the tab name when the user selects the corporate address book.
If the address book service is provided by Oracle Communications Contacts Server, see the Contacts Server documentation for information about changing the name of the corporate address book. Because the display name of the corporate address book is being provisioned by Contacts Server, it is not possible to localize the name in Convergence.
For a new user, a user whose corporate entry has previously been deleted from Directory Server, or if new corporate directories are added to the deployment, you can use the ab.corpdir.[identifier].description and ab.corpdir.[identifier].displayname configuration parameters to change the name of the Corporate Directory tab in the Convergence Address Book.
But, if a corporate directory entry already exists for the end user, the ab.corpdir.[identifier].description and ab.corpdir.[identifier].displayname configuration parameters do not display the new corporate directory name. Instead, the default name, Corporate Directory, displays. The following instructions explain how to customize the corporate directory name for all users in a domain. You can use this example for both existing and new directory entries without having to change the displayName entries in o=PiServerDb for every user.
To change the name Corporate Directory:
Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
/c11n_Home/allDomain/nls/
In c11n_Home, verify that config.js exists. If it does not exist, create it.
Modify config.js so that it enables i18n customization (i18nEnabled: true) across all domains (module: "allDomain").
dojo.provide("c11n.config");
c11n.config = {
// allDomain configuration
allDomain: {
module: "allDomain", // module name
themeEnabled: false, // true if theme is customized
i18nEnabled: true, // true if i18n is customized
jsEnabled: false // true if js is customized
// the last entry must not end with comma
}
}
In c11n_Home/allDomain/nls, create a default resource file named resources.js.
This customized resources file inherits the default values in the standard resources file and extends them with the new, custom values. At run time, for each domain that has i18nEnabled enabled, Convergence loads that domain's l10n resource file, named resources.js. The resources.js file in the default directory is loaded first; then the resources.js in this customization directory is loaded. Thus, Convergence first loads the standard values (including labels) in the default resources file; it then overrides those values with any customizations.
In resources.js, remove any references to corporate directory (for example, corp_dir, the_corporate_directory, corporate_lookup, or corp_dir_lookup).
In resources.js, add the following:
{
corporate_directory: "Example Directory", //where "Example Directory" is your Corporate Directory's name
last: ""
}
Restart the Oracle certified application server and clear the browser cache to see the change.
By default, when inviting contacts to an event from the corporate directory, contacts are listed by Display Name (LDAP attribute "cn") and Email (LDAP attribute "mail").
You can customize the Add Contacts dialog box to display additional columns of information.
This example shows how to add Job Title (LDAP attribute "title") and Department (LDAP attribute "ou") to the list of attributes when inviting contacts from the corporate directory to an event.
Note:
The LDAP attribute to Convergence attribute mapping for Corporate Directory is in this file: /var/opt/sun/comms/iwc/config/templates/ab/corp-dir/xlate-inetorgperson.xmlThe LDAP attribute to Convergence attribute mapping for Personal Address Book is in this file: /var/opt/sun/comms/iwc/config/templates/ab/ldappstore/xlate-piTypePerson.xml
Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
/c11n_Home/allDomain/js/widget/addressBook
In c11n_Home, verify that config.js exists. If it does not exist, create it.
Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").
dojo.provide("c11n.config");
c11n.config = {
// allDomain configuration
allDomain: {
module: "allDomain", // module name
themeEnabled: false, // true if theme is customized
i18nEnabled: false, // true if i18n is customized
jsEnabled: true // true if js is customized
// the last entry must not end with comma
}
}
In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
dojo.provide("c11n.allDomain.js.customize");
dojo.require("c11n.allDomain.js.widget.addressBook._FilteringQuerierMixin");
dojo.require("c11n.allDomain.js.widget.addressBook.BookStoreItemSelector");
In c11n_Home/allDomain/js/widget/addressBook, create or modify _FilteringQuerierMixin.js to include the following code:
dojo.provide("c11n.allDomain.js.widget.addressBook._FilteringQuerierMixin");
dojo.require("iwc.widget.addressBook._FilteringQuerierMixin");
dojo.setObject("iwc.widget.addressBook._FilteringQueryCellTypes", {
"entry/displayname": {
l10nKey: "display_name",
field: "entry/displayname",
formatter: function(value){
// displayname could be an array in corporate.
return dojo.isArray(value) ? iwc.util.encodeXMLEntities(value[0]) : value;
},
width: "25%",
noresize: true
},
"organization/title": {
l10nKey: "job_title",
field: "organization/title",
formatter: function(value){
return dojo.isArray(value) ? iwc.util.encodeXMLEntities(value[0]) : value;
},
width: "25%",
noresize: true
},
"organization/organizationalunit": {
l10nKey: "department",
field: "organization/organizationalunit",
formatter: function(value){
return dojo.isArray(value) ? iwc.util.encodeXMLEntities(value[0]) : value;
},
width: "25%",
noresize: true
},
"email": {
l10nKey: "email",
field: 'email',
formatter: function(value){
// email is multivalued... will return an array
return value === undefined ? "" : iwc.util.encodeXMLEntities(value[0].content);
},
width: "25%",
noresize: true
}
});
In c11n_Home/allDomain/js/widget/addressBook, create or modify BookStoreItemSelector.js to include the following code:
dojo.provide("c11n.allDomain.js.widget.addressBook.BookStoreItemSelector");
dojo.declare("iwc.widget.addressBook.BookStoreItemSelector", iwc.widget.addressBook.BookStoreItemSelector, {
displayColumns: ["entry/displayname", "email", "organization/title", "organization/organizationalunit"],
last: ""
});
Restart the Oracle certified application server and clear the browser cache.
By default, when inviting resources to an event from the corporate directory, resources are listed by Display Name (LDAP attribute "cn") and Email (LDAP attribute "mail").
You can customize the Add Resources dialog box to display additional columns of information.
This example builds on the example "Displaying Additional Address Book Attributes When Adding Contacts to an Invitation".
This example shows how to add Job Title (LDAP attribute "title") and Department (LDAP attribute "ou") to the list of attributes when inviting resources from the corporate directory to an event.
In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code in bold:
dojo.provide("c11n.allDomain.js.customize");
dojo.require("c11n.allDomain.js.widget.addressBook._FilteringQuerierMixin");
dojo.require("c11n.allDomain.js.widget.addressBook.BookStoreItemSelector");
dojo.require("c11n.allDomain.js.widget.addressBook.ResourceStoreItemSelector");
In c11n_Home/allDomain/js/widget/addressBook, create or modify ResourceStoreItemSelector.js to include the following code:
dojo.provide("c11n.allDomain.js.widget.addressBook.ResourceStoreItemSelector");
dojo.require("iwc.widget.addressBook.ResourceStoreItemSelector");
dojo.declare("iwc.widget.addressBook.ResourceStoreItemSelector",
iwc.widget.addressBook.ResourceStoreItemSelector, {
displayColumns: ["entry/displayname", "email", "organization/title", "organization/organizationalunit"],
last: ""
});
Restart the Oracle certified application server and clear the browser cache.
You can limit a user's ability to copy corporate address book contacts to their personal address book by removing the Copy To button from the Address Book UI.
Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
/c11n_Home/allDomain/js/widget/addressBook/
In c11n_Home, verify that config.js exists. If it does not exist, create it.
Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").
dojo.provide("c11n.config");
c11n.config = {
// allDomain configuration
allDomain: {
module: "allDomain", // module name
themeEnabled: false, // true if theme is customized
i18nEnabled: false, // true if i18n is customized
jsEnabled: true // true if js is customized
// the last entry must not end with comma
}
}
In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
dojo.provide("c11n.allDomain.js.customize");
dojo.require("c11n.allDomain.js.widget.addressBook._BookBrowserToolbar");
In c11n_Home/allDomain/js/widget/addressBook, create or modify _BookBrowserToolbar.js to include the following code:
dojo.provide("c11n.allDomain.js.widget.addressBook._BookBrowserToolbar");
dojo.require("iwc.widget.addressBook._BookBrowserToolbar");
dojo.declare("iwc.widget.addressBook._BookBrowserToolbar",
iwc.widget.addressBook._BookBrowserToolbar, {
buildRendering: function() {
// invoke the original buildRendering()
this.inherited(arguments);
dojo.style(this.copyToolbarButton.domNode, "display", "none"); // remove the copyTo button
},
last: ""
});
Restart the Oracle certified application server and clear the browser cache to see the change.
By default, the Convergence personal address book automatically creates a link to Google Maps when a contact profile includes an address.
To remove the link to Google Maps:
Verify that the c11n_Home directory exists. If c11n_Home does not exist, create it.
Verify that customization is enabled in Convergence. If customization is disabled, enable it.
In c11n_Home, verify that the following directories exist. If they do not exist, create them:
/c11n_Home/allDomain/js/service/ /c11n_Home/allDomain/js/widget/addressBook/
In c11n_Home, verify that config.js exists. If it does not exist, create it.
Modify config.js so that it enables JavaScript customization (jsEnabled: true) across all domains (module: "allDomain").
dojo.provide("c11n.config");
c11n.config = {
// allDomain configuration
allDomain: {
module: "allDomain", // module name
themeEnabled: false, // true if theme is customized
i18nEnabled: false, // true if i18n is customized
jsEnabled: true // true if js is customized
// the last entry must not end with comma
}
}
In c11n_Home/allDomain/js, create or modify customize.js (the domain specific customization) to include the following code:
dojo.provide("c11n.allDomain.js.customize");
// Hide Google Maps link
dojo.require("c11n.allDomain.js.widget.addressBook._DisplayContactBody");
In c11n_Home/allDomain/js/widget/addressBook, create or modify _DisplayContactBody.js. Find the _DisplayContactBody method and replace it with the following:
dojo.provide("c11n.allDomain.js.widget.addressBook._DisplayContactBody");
dojo.require("iwc.widget.addressBook._DisplayContactBody");
dojo.declare("iwc.widget.addressBook._DisplayContactAddressValue",iwc.widget.addressBook._DisplayContactAddressValue, {
postCreate: function() {
this.inherited(arguments);
// hide the google maps in the address field
dojo.addClass(this.mapLinkNode, "dijitHidden");
},
last: ""
});
Restart the Oracle certified application server and clear the browser cache to see the change.
Unless the Convergence address book is provided by Contacts Server, you can customize Convergence so that users can export and import address book information in a custom language.
This example assumes you have completed the example "Adding a New Language in Convergence"
Configure Convergence to export address book data in the custom language:
In /var/opt/sun/comms/iwc/config/templates/ab/export, create a file named export-csv-language.xls, where language is language code for your custom language. For example, if your custom language is Slovak, create export-csv-sk.xls.
You can create this file by copying and renaming another CSV file with the following command:
diff export-csv-us.xsl export-csv-language.xsl
Modify export-csv-language.xls with column labels in the custom language.
Convergence can now export address book data in CSV format in the custom language.
Configure Convergence to import address book data in the custom language:
In /var/opt/sun/comms/iwc/config/templates/ab/import, modify headrXlations.orig to add mappings and translations for the custom language:
diff headrXlations.orig headrXlations
For example, if the custom language is Slovak:
> [sk] > sk-First Name=First Name > sk-Last Name=Last Name > sk-Middle Name=Middle Name > sk-Name=Name > sk-Nick Name=Nick Name > sk-Email=E-mail Address
In /var/opt/sun/comms/iwc/config/templates/ab/import, create xlate-csvlanguage.xml, where language is the custom language. For example, xlate-csvsk.xml:
You can create this file by copying and renaming another XML file with the following command:
diff xlate-csvus.xml xlate-csvlanguage.xml
In /var/opt/sun/comms/iwc/config/templates/ab/import, modify import.properties to include the following code:
import.csvlanguage.class = com.sun.comms.client.ab.importexport.ImportedCsvParser import.csvlanguage.xlatePath = csvlanguage import.csvlanguage.encoding = ISO-8859-1 language.charset=ISO-8859-1
For example, if the custom language is Slovak:
import.csvsk.class = com.sun.comms.client.ab.importexport.ImportedCsvParser import.csvsk.xlatePath = csvsk import.csvsk.encoding = ISO-8859-1 sk.charset=ISO-8859-1
Convergence can now import address book data in CSV format in the custom language.