Oracle Siebel CRM 8 Developer's Handbook

Transcription

1 P U B L I S H I N G professional expertise distilled Oracle Siebel CRM 8 Developer's Handbook Alexander Hansal Chapter No.13 "User Properties"

2 In this package, you will find: A Biography of the author of the book A preview chapter from the book, Chapter NO.13 "User Properties" A synopsis of the book s content Information on where to buy this book About the Author Alexander Hansal has worked for various companies and governmental institutions as IT instructor and consultant. He started as a Siebel CRM instructor for Siebel Systems Germany in Since the acquisition of Siebel Systems by Oracle, Alexander has continued to support European customers as instructor and consultant for Siebel CRM and Oracle Business Intelligence. Strongly believing in the power of information sharing, Alexander regularly discusses Siebel CRM and Oracle BI related topics on his weblog (

3 Oracle Siebel CRM 8 Developer's Handbook Siebel CRM, Oracles' market-leading Customer Relationship Management software, can be tailored to customers needs. In this book, the ambitious developer will learn how to safely implement customer requirements in Siebel CRM using Siebel Tools, Siebel's own integrated development environment. This book is a complete practical guide to Siebel Tools and how it can be used to implement custom requirements. The book teaches you to configure the Siebel CRM user interface objects as well as the underlying business layer objects by using real-life case study examples. In addition, you will learn to safely configure the Siebel data model. Understanding and using the Siebel Event Framework for automation is also a key focus area of the book. You will gain a thorough and solid understanding of integration objects to support EAI interfaces. Chapters on Siebel Workflow, Task UI, and scripting prepare you for the most complex automation requirements. This book uses a real-life case study to provide easy-to-follow examples for the majority of chapters. The examples are radically practical and can be easily adapted to similar situations in Siebel CRM implementation projects. The book ensures that you know what you are doing and why you are doing it by providing useful insight along with detailed practice instructions. The book contains a multitude of explanatory tables, screenshots, and precise diagrams to illustrate the topics. When you have finished the book, you will feel prepared to participate in Siebel CRM implementation projects. In addition you will be able to teach the old dog some new tricks. What This Book Covers Chapter 1, Siebel Tools and the Siebel Repository, introduces you to the user interface of Siebel Tools and the object definitions that form the Siebel Repository. Chapter 2, Developer Tasks, lays the foundation for a solid understanding of common tasks in the development cycle. Chapter 3, Case Study Introduction, provides an introduction to All Hardware, a fi ctitious company whose requirements serve as case study examples throughout the remaining chapters.

4 Chapter 4, Symbolic Strings, discusses the concept of symbolic strings, the central library of translatable texts that can be referenced from any object, that displays text in the user interface. Chapter 5, Creating and Configuring Applets, teaches you how to create and modify form applets and list applets. Chapter 6, Views and Screens, describes how to configure views and screens as well as how to register views in a responsibility. Chapter 7, Business Components and Fields, introduces you to the important concepts of the Siebel business logic layer. You will learn how business components and their fields lay the foundation of the logical data model and how to configure them. Chapter 8, The Data Layer, enables you to identify configuration options for objects that define the physical data model, such as tables, their columns and indexes. Chapter 9, Business Objects and Links, completes the discussion of the business logic layer by introducing the concept of business objects and links. As in all chapters before, case study examples allow you to deepen your knowledge by providing a hands-on experience. Chapter 10, Pick Lists, enables you to create static and dynamic pick lists on business component fields. Chapter 11, Multi Value Fields, provides insight on how to configure multi value fields and their counterparts in the Siebel user interface. Chapter 12, Configuring Access Control, shows how to configure business components to work within the Siebel Access Control framework in order to ensure data security. Chapter 13, User Properties, introduces an important configuration option that allows developers to define specialized application logic while staying within safe declarative boundaries. Chapter 14, Configuring Navigation, uses a case study example to explore the various possibilities of providing static and dynamic drilldowns as well as toggle applets. Chapter 15, Customizing the Look and Feel of Siebel Applications, enables you to modify Siebel Web Templates and style sheets in a safe manner. Chapter 16, Menus and Buttons, introduces the Siebel Event Framework and how to use it to configure user interface elements such as menu items, applet buttons, and toolbar buttons. Chapter 17, Business Services, starts an exploration of the Siebel automation capabilities by introducing the concept of business services. You will learn about important preconfigured business services and how to invoke their methods.

5 Chapter 18, Supporting Integration Interfaces, brings information about integration objects and how to use them to support EAI interfaces. The chapter also introduces the EAI Siebel Adapter business service. Chapter 19, Siebel Workflow, is the first of two chapters that explain the concepts and configuration options of Siebel Workflow processes. The chapter explains in detail how to create, simulate, and deploy workflow processes. Chapter 20, Advanced Siebel Workflow Topics, explains how to use exception handling, sub processes, loops, and other advanced techniques within Siebel Workflow processes. Chapter 21, Siebel Task User Interface, introduces the Siebel Task UI and teaches you how to configure, test, and deploy task flows to allow better business process support for end users. Chapter 22, Extending Siebel CRM Functionality with escript, begins with an introduction to the Siebel scripting framework, discusses important aspects of the Siebel escript language and shows you how to write a custom business service. Chapter 23, Advanced Scripting Techniques, discusses topics such as browser scripting, translatable messages, and tracing while providing real-life examples. Chapter 24, Deploying Configuration Changes between Environments, introduces the developer to techniques to migrate changes made to the Siebel Repository, administrative data, and fi les from the development environment to other environments. Appendix A, Installing a Siebel CRM Self-Study Environment, guides you through the necessary steps to downloading and installing Siebel CRM software for a self-study environment.

6 User Properties Many business requirements are very detailed and complex. For example, the end user community could demand that one field is updated automatically when another field has been changed. To solve this kind of requirement in Siebel CRM, developers can define so-called user properties as an extension to the standard properties of object types such as business components, fields, and applets. In this chapter, we will discuss the following topics: Understanding user properties Business component and field user properties Applet, control, and list column user properties Viewing user properties Understanding user properties User properties are child object types that are available for the following object types in the Siebel Repository: Applet, Control, List Column Application Business Service Business Component, Field Integration Object, Integration Component, Integration Component Field View

7 User Properties To view the User Property (or User Prop as it is sometimes abbreviated) object type we typically have to modify the list of displayed types for the Object Explorer window. As discussed in the previous chapter, this can be achieved by selecting the Options command in the View menu. In the Object Explorer tab of the Development Tools Options dialog, we can select the object types for display as shown in the following screenshot: In the preceding example, the Business Component User Prop type is enabled for display. After confirming the changes in the Development Tools Options dialog by clicking the OK button, we can for example navigate to the Account business component and review its existing user properties by selecting the Business Component User Prop type in the Object Explorer. The following screenshot shows the list of user properties for the Account business component: [ 244 ]

8 Chapter 13 The screenshot also shows the standard Properties window on the right. This is to illustrate that a list of user properties, that mainly define a Name/Value pair can be simply understood as an extension to an object type's usual properties, which are accessible by means of the Properties window and represent Name/Value pairs as well. Because an additional user property is just a new record in the Siebel Repository, the list of user properties for a given parent record is theoretically infinite. This allows developers to define a rich set of business logic as a simple list of Name/Value pairs instead of having to write program code. The Name property of a user property definition must use a reserved name and optional sequence number as defined by Oracle engineering. The Value property must also follow the syntax defined for the special purpose of the user property. Did you know? The list of available names for a user property depends on the object type (for example Business Component) and the C++ class associated with the object definition. For example, the business component Account is associated with the CSSBCAccountSIS class, which defines a different range of available user property names than other classes. Many user property names are officially documented in the Siebel Developer's Reference guide in the Siebel Bookshelf. We can find the guide online at the following URL: ToolsDevRef_UserProps.html The user property names described in this guide are intended for use by custom developers. Any other user property that we may find in the Siebel Repository but that is not officially documented should be considered an internal user property of Oracle engineering. Because the internal user properties could change in a future version of Siebel CRM in both syntax and behavior without prior notice, it is highly recommended to use only user properties that are documented by Oracle. Another way to find out which user property names are made available by Oracle to customers is to click the drop-down icon in the Name property of a user property record. This opens the user property pick list, which displays a wide range of officially documented user properties along with a description text. [ 245 ]

9 User Properties Multi-instance user properties Some user properties can be instantiated more than once. If this is the case a sequence number is used to generate a distinguished name. For example, the On Field Update Set user property used on business components uses a naming convention as displayed in the following screenshot: In the previous example, we can see four instances of the On Field Update Set user property distinguished by a sequential numeric suffix (1 to 4). Because it is very likely that Oracle engineers and custom developers add additional instances of the same user property while working on the next release, Oracle provides a customer allowance gap of nine instances for the next sequence number. In the previous example, a custom developer could continue the set of On Field Update Set user properties with a suffix of 13. By doing so, the custom developer will most likely avoid conflicts during an upgrade to a newer version of Siebel CRM. The Oracle engineer would continue with a suffix of five and upgrade conflicts will only occur when Oracle defines more than eight additional instances. The gap of nine also ensures that the sequence of multi-instance user properties is still functional when one or more of the user property records are marked as inactive. In the following sections, we will describe the most important user properties for the business and user interface layer. In addition, we will examine case study scenarios to identify best practices for using user properties to define specialized behavior of Siebel CRM applications. Business component and field user properties On the business layer of the Siebel Repository, user properties are widely used to control specialized behavior of business components and fields. The following table describes the most important user properties on the business component level. The Multiple Instances column contains Yes for all user properties that can be instantiated more than once per parent object: [ 246 ]

10 Chapter 13 User Property Name Description Multiple Instances Active Field These two user properties define the name No Active Value of a business component field and a value of that field. When the field has the value defined in the Active Value user property then the record is considered Active and can be updated. Otherwise, the record is considered Inactive and cannot be updated. Admin NoDelete When the value of these user properties is No Admin NoUpdate set to Y, the business component prevents deletions or updates (respectively) even when the business component is in Admin mode. All Mode Sort Allows developers to control how data is No View Mode Sort sorted for views that potentially display a large number of records (for example, Manager, All, Organization view modes). A value of Normal indicates that the business component's sort specification will be used for sorting. A value of TRUE switches the sort order to the U1 index of the underlying table. A value of FALSE results in no sorting. The View Mode Sort user property allows defining a sort specification for various view modes when All Mode Sort is set to FALSE. BC Read Only Field The value of this user property is typically the No name of a calculated field that returns Y or N. When the value is Y the record is read-only, otherwise the record can be updated as usual. Currency Field Specifies the name of a field in its parent business component. When the currency of this field is changed, a new value for this field is calculated based on the exchange rates stored for the currency pair in the Siebel database. Yes [ 247 ]

11 User Properties User Property Name Description Multiple Instances Deep Copy Deep Delete Deep Copy/Delete Link These user properties control the behavior of the parent business component and child business components when a parent record is copied or deleted. Yes Recursive Link Deep Copy specifies the name of the child business component in a 1:M relationship with the parent business component whose records are copied to the parent copy. Deep Delete defines the name of a child business component whose records will be deleted when the parent record is deleted. Disable Automatic Trailing Wildcard Field List Field Read Only Field: fieldname Named Method No Clear Field NoDelete Field The Deep Copy/Delete Link and Recursive Link user properties allow defining the link object definitions that should be used to determine the set of child records for the deep copy or delete operations. The value of this user property is a list of field names for which the automatic trailing wildcard behavior, automatically appending an asterisk sign (*) to the query string, should be disabled. A reference to a Boolean field. When the field returns Y, the field specified in the fieldname suffix of the user property's name becomes read-only. Allows developers to specify an action to be executed when a method is invoked on the business component. This user property is discussed in greater detail in the following section. The value of this user property is the name of a field in the parent business component. When set, the field cannot be set to NULL. Can be specified once per parent business component. When the field specified by the user property returns Y then the entire record is protected from being deleted. No Yes Yes Yes No [ 248 ]

12 Chapter 13 User Property Name Description Multiple Instances On Condition Set Field Value On Field Update Invoke On Field Update Set The value of this user property specifies a condition, a target field name, and a value to which the target field is set when the condition evaluates to TRUE. Specifies a field in the parent business component, a target business component, and a target method, which is invoked on the target business component when the field is updated. Specifies a field in the parent business component, a target field, and a value to which the target field is set when the field is updated. Example Value: Yes Yes Yes Parent Read Only Field Recipient "Primary Owner Id", "Manual Asgn Flag", "Y" Specifies a field in a business component to which the current business component has a child relationship. When that field returns Y, all records in the current business component are read-only. The user properties with a name starting with Recipient allow controlling the behavior of Siebel CRM applications during communication with customers such as sending or fax messages. No Yes Source: Siebel Developer's Reference, Version 8.1: booktitle.html Named method user property The Named Method user property can be specified on the business component and applet level. It is of major importance for implementing automated event flows in Siebel CRM applications. [ 249 ]

13 User Properties For example, we can expose a button on a sales order form applet that allows the end user to send the current sales order to an external system. The complex processing of the order data and the invocation of the EAI interface are implemented as a Siebel workflow process. The invocation of the workflow process can be implemented with the Named Method user property on the business component level thus providing business logic support for all applets that are based on the business component. The syntax for the Named Method user property on the business component level is as follows: Name: Named Method N Value: "Method Name", "Action Type", "Object", "Action Parameters" The key words in the Value field must be enclosed in double quotes and must be separated by a comma followed by a space. In the following section, we will discuss the key words in greater detail: N: An integer number that defines the sequence in case there are multiple definitions for the Named Method user property. As indicated above, Siebel CRM does not allow sequence gaps greater than nine. In addition, only two-digit sequence numbers are allowed. So the maximum number of instances for a single user property name is 99. Method Name: The name of the method. When the method is invoked the action defined by the following parameters is executed. Object: Depending on the action type, the object can be a business component field or a business component against which the action is executed. Action Parameters: Except for the INVOKESVC action type (described as follows), only one action parameter is required. The action parameter is typically a value or an expression, in Siebel Query Language, that returns the value for the action. Action Type: The Siebel CRM framework provides three major types of actions, SET, INVOKE, and INVOKESVC, which are described in the following table: [ 250 ]

14 Chapter 13 Action Type Description Example Value and Explanation SET INVOKE INVOKESEL INVOKEALL Allows setting a field, specified as the object, to the return value of an expression, specified as the action parameter. With this action type, the object is the name of a business component and the action parameter is the name of a method to invoke on the object business component. Similar to INVOKE but invokes the method for all selected records of the object business component. Similar to INVOKE but invokes the method for all records of the object business component. "ViolationTrue", "SET", "Protocol Violation", "'Y'" Explanation: When the ViolationTrue method is invoked, the Protocol Violation field is set to Y. "Ungroup", "INVOKE", "Quote Item", "WriteRecord" Explanation: When the Ungroup method is invoked on the current business component, the WriteRecord method is invoked on the Quote Item business component. "UpdateOptyProdQty", "INVOKEALL", "Opportunity Product", "UpdateOptyProdQty" Explanation: When the UpdateOptyProdQty method is invoked on an Opportunity record, the same method is invoked on all associated Opportunity Product records. [ 251 ]

15 User Properties Action Type Description Example Value and Explanation INVOKESVC The INVOKESVC action type is used to invoke business service methods and pass input arguments for these methods. The object is a business component. The action parameters are the name of the business service, the name of the method, and a list of name/value pairs for the input arguments. "UpdateProgram", "INVOKESVC", "LOY Program", "Workflow Process Manager", "RunProcess", "ProcessName", """LOY Update Program Process""", "RowId", "[Id]" Explanation: When the UpdateProgram method is invoked, the Workflow Process Manager business service's RunProcess method will be invoked. The input argument ProcessName will be set to LOY Update Program Process. The input argument RowId will be set to the value of the Id field of the current record in the LOY Program business component. Note: To provide a double quote as the input, for example to enclose a string that contains spaces such as LOY Update Program Process in the preceding example, we must specify two double quotes in order to escape. This explains why the process name is enclosed in three double quotes. [ 252 ]

16 Chapter 13 Action Type Description Example Value and Explanation INVOKESVCSEL INVOKESVCALL Similar to the INVOKESVC action type but invokes the business service method for the currently selected records of the object business component. Similar to the INVOKESVC action type but invokes the business service method for all records of the object business component. "CalculateRoomBlockRates", "INVOKESVCSEL", "TNT SHM Sub Opportunity", "TNT SHM Recurring Events", "CalculateRoomBlockRates" Explanation: When the CalculateRoomBlockRates method is invoked, the CalculateRoomBlockRates method of the TNT SHM Recurring Events business service will be invoked for all selected records of the TNT SHM Sub Opportunity business component. We will learn how to use the Named Method user property in an upcoming chapter. Case study example: Using the On Field Update Set user property In Chapter 5, Creating and Configuring Applets we created the AHA Customer Profile Form Applet. One of the controls in this applet should display the timestamp when the customer's status was last updated. We have already placed the control, which maps to the Account Status Date field in the Account business component, on the applet but it is not yet functional. The following procedure describes how we can create a new instance of a business component user property named On Field Update Set in the Account business component. This user property will enforce an update with the current timestamp on the Account Status Date field when the Account Status field has been updated: 1. If necessary, configure the Object Explorer window so that the Business Component User Prop type is exposed. 2. Navigate to the Account business component. 3. Ensure that you have write access to the account business component. [ 253 ]

17 User Properties 4. In the Object Explorer, navigate to the Business Component User Prop type. 5. Query for all user properties that have names starting with On Field Update Se. 6. Copy the existing user property named On Field Update Set 2. This user property has a value of "Managers Review", "Last Manager Review Date", Timestamp() in the Siebel SIA repository. 7. Rename the copy to On Field Update Set 14. The highest sequence number of active On Field Update Set user properties is 5, so we can add the customer allowance gap of nine to it. If the sequence numbers in your working repository should be different for any reason, please adjust the numbering accordingly. 8. Modify the value of the new user property as follows: "Account Status", "Account Status Date", Timestamp() Ensure that each comma is followed by a space. 9. Set the Comments to Created for AHA prototype. 10. Step off the record to save it. 11. Navigate to the Account Status Date field and set the following properties: Type: DTYPE_DATETIME Comments: Changed Type from DTYPE_DATE to DTYPE_DATETIME for AHA prototype 12. Compile the Account business component. To test the changes, we can launch the Siebel Developer Web Client and navigate to the Process Start Page view in the Accounts screen. It may be necessary to create a test customer account. We can then continue the test cycle by modifying the customer's Status field and using the Tab key to move to the next control. We should be able to observe that the Last Status Update control now displays the current date and time. [ 254 ]

18 The following screenshot shows the Last Status Update field after changing the customer's status to Contract Pending: Chapter 13 A Siebel Tools archive file (Account BC.sif) is provided with this chapter's code files. The file represents the Account business component after the changes in the preceding section. Field user properties The following table describes prominent user properties that we can use to control the behavior of individual business component fields: User Property Description DisableSearch When set to TRUE, wildcard searches using an asterisk (*), which may negatively impact query performance on the parent field, are not possible. The value can be delivered by a calculated field or an expression to dynamically enable or disable wildcard searches. DisableSort When set to TRUE, sorting is disabled on the parent field. This is indicated to the end user by the text Not Sortable displayed in the tool tip on the list column. The value can be delivered by a calculated field or an expression to dynamically enable or disable sorting. Encrypt Several user properties allow defining field level encryption as well as masking of field values, for example credit card Display Mask Char numbers, in the user interface. Required The value of this user property is typically the name of a calculated field. When this field returns Y, the parent field of the user property cannot be empty. Text Length Override When this user property is present, the Text Length property of its parent field determines the maximum possible length of the field text. The value of this user property is irrelevant. The maximum possible text length of a field is normally determined by the physical length of the underlying database table column. Source: Siebel Developer's Reference, Version docs/cd/e14004_01/books/toolsdevref/booktitle.html [ 255 ]

19 User Properties Applet, control, and list column user properties The Applet object type provides user properties on the applet level itself as well as on the control and list column level (for list applets only). The following table describes some of the most important applet user properties: User property CanInvokeMethod: methodname Default Applet Method Default Focus Named Method N: methodname NoDataHide Description This user property allows controlling whether a button or menu item on the applet is enabled (clickable) or disabled (grayed out and not clickable). The name of the method invoked by the button or by the command behind the menu item is specified as the second part of the name (after a colon and a space). The value of this user property can be either a string TRUE or FALSE or eventually Y or N or an expression that must evaluate to TRUE or FALSE. Example: Name: CanInvokeMethod: CancelFunction Value: [Freeze Flag] <> "Y" Explanation: Buttons or menu items exposing the CancelFunction method will only be clickable when the value of the Freeze Flag field is not Y. The value of this applet user property is the name of a method that is provided by the applet's buttons or menu items. The end user can simply press the Enter key to invoke the method. It is possible to set the focus of a control or list column that is not the first in the display sequence by using the Default Focus user properties. This may allow faster access to the control or list column for end users. The user property can be defined individually for each template type such as Edit, New, and Query. The syntax for the Named Method user property on the applet level differs slightly from the business component level: the name of the method is defined as the second part of the user property name (after a colon and a space). When the value of this user property is set to Y, the applet will not be displayed when there is no data to display. [ 256 ]

20 Chapter 13 Control user properties The most notable user properties for Control objects are related to navigation events. The Url user property must be added to a button control that invokes the GotoUrl method and specifies the target URL. The View user property is a child object definition of a button control that invokes the GotoView method and defines the view to which the Siebel application navigates when the button is clicked. List column user properties The List Column object type supports the DisableSort user property that allows controlling the presence or absence of sorting functionality for a specific list column rather than for all list columns in potentially many applets (when defined on the field level). View user properties The only officially documented user property for the View object type is DefaultAppletFocus. The value of this user property is the name of one of the view's applets. The applet will have focus when the view is loaded. Summary User properties are a powerful resource for defining special application behavior and business logic. They are provided as an alternative to writing custom script code by Oracle engineering. Because user properties are often limited to certain classes, in the case of business components and applets, their functionality is not always easy to understand. In this chapter, we introduced the most important user properties for business components, fields, applets, controls, list columns, and views. In the next chapter, we will learn how to support navigation concepts such as drilldowns, applet toggles, and the thread bar. [ 257 ]

21 Where to buy this book You can buy Oracle Siebel CRM 8 Developer's Handbook from the Packt Publishing website: developers-handbook-raw/book. Free shipping to the US, UK, Europe and selected Asian countries. For more information, please read our shipping policy. Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet book retailers. P U B L I S H I N G professional expertise distilled