Enhance the CRM WebClient UI with Custom Fields

by Boris Dingenouts, Senior SAP CRM Consultant, and Manuel Dekker, Senior SAP CRM Development Consultant

Walk through a step-by-step example of how to enhance the new CRM WebClient UI. With SAP CRM 2006s and SAP CRM 2007, you do not need programming experience to customize your CRM WebClient UI screens.

Key Concept
The business role determines the functionalities a user can access. Within the business role, the config key determines the screens the user sees. SAP CRM 2006s and SAP CRM 2007 offer significant updates to the SAP CRM application. The main advantage for implementation specialists is that the new releases deliver an easy-to-use configuration workbench. This makes it possible for functional consultants with very little technical background to define the screen layouts without programming. In this article we share our experience in defining screen layouts in the new releases. In our example, our company sends different colors of golf balls for promotional purposes, so we want to record the favorite color of each contact person in SAP CRM. This is not a standard SAP field, so we need to add the field Favourite colour to the contact person overview page. To fulfill this requirement, we need to carry out the following steps: Step 1. Identify the component to enhance Step 2. Create the enhancement set Step 3. Enhance the component Step 4. Enhance the view Step 5. Enhance the context node Step 6. Add the field

Step 7. View configuration Although this process applies to both SAP CRM 2006s and SAP CRM 2007, we are using SAP CRM 2006s for the steps in this example. In SAP CRM 2007, the process differs slightly. For example, in SAP CRM 2007 edit pages are usually displayed within the assignment block, whereas in SAP CRM 2006s they are not. Also, SAP CRM 2007 SP1 no longer requires display pages. Technical Background To fully understand all the steps and concepts described in this article, you need some technical background. Programming experience is not required, but you must be familiar with a few key concepts in programming. Two main concepts in the CRM WebClient UI you must know to fully understand and apply the concepts of this article are the business roles and config key. The most central concept within the CRM WebClient UI is the business role. It determines which functionalities are available for the user for example, marketing or sales manager functionality. Each business role contains a config key that determines which version of the screens the user can see. You can use this to differentiate between a sales manager and a sales assistant, for instance. Both need to be able to change customer data, but the sales assistant should see fewer fields or different reports. Both user types have different business roles linked to different config keys, so they see different versions of the same screen. In the CRM WebClient UI, these screens are called views and the different versions are called configurations. Were going to use an example view, the contact person overview page, to show how to create different configurations of this view and link them to the appropriate business roles. Step 1. Identify the Component to Enhance To start the CRM WebClient UI, go to the Component Workbench (transaction BSP_WD_CMPWB). The main application for the CRM WebClient UI is the CRM_UI_FRAME component. Enter CRM_UI_FRAME in the Component field and click on the Test button. An Internet browser window opens with the standard SAP NetWeaver Application Server login page. Enter your normal SAP credentials to log on. For our example, we want to add a field to the contact persons master data. Lets start with the standard contact person create page. After a successful login, the system displays the home page where you can access all the relevant functionality that your business role provides. Access the contact person create page by clicking on Account Mngmnt on the left side of the home page. The main section of the page on the right side contains a collection of links to Account Management functionality. Here you find the Contact link under the Create heading in the right column. Click on this link to go to the contact person create page (Figure 1).

Figure 1

The standard contact person create page

In this example, we want to place a new field called Favourite colour directly under the Language field. This new field should have a drop-down menu that contains a list of colors. The system should display this field on the contact person details and change pages where the user can modify the color. The CRM WebClient UI functionality is divided into technical parts called components. To work on a component, you need to know its technical component name so you can enter that name in the component workbench transaction. In Figure 1, click on the ID field and press F2. The system displays a pop-up screen that contains the technical data in the Component field, BP_CONT in our example (Figure 2).

Figure 2 Note

Press F2 to view the technical data for each field

In the traditional SAPGUI client, you can press F1 and then click on the technical information icon to learn more about a screen field, the current program, and the current screen. In the CRM WebClient UI, you must press F2 to learn more about the current field, component, and view. Next, go back to transaction BSP_WD_ CMPWB (Component Workbench). In the screen that appears, enter BP_CONT in the Component field and press Enter. The View field in Figure 2 informs you that you are in view ContactNewDetailsEF. Expand the Views and double-click on the BP_CONT/ContactNewDetailsEF view (Figure 3).

Figure 3 Note

Overview of the BP_CONT component in the Component Workbench

CRM WebClient UI components use the Model-View-Controller (MVC) approach for creating Web applications. If you have experience with Web Dynpro development or Interaction Center in previous CRM releases, you will be familiar with it. Each component has a component controller that holds everything together and provides for interaction with other components. Views are the visible part of the component. A view has a layout that provides fields, buttons, and other visible elements, a controller that takes care of any interaction between the view and the user, and a model that holds the data. The screen in Figure 2 contains a field called Context Node that has the value BUILHEADER. If you look at Figure 3, you can see a line called Context just below the implementation class on the right side. Expand the line by clicking on the triangular icon just to the left and the system displays several new lines. The last one displays Context Node. Expand this line, too, and all context nodes of this view are displayed. Here you find the BUILHEADER context node. Before you can add the new field to the context node, you have to perform a few more steps. Step 2. Create the Enhancement Set

When you entered the Component Workbench, you may have noticed the enhancement icon to the left of the Component field. Clicking on this icon displays a field called Enhancement Set to the right of the Component field. You need to define this enhancement set. All changes to components are done using this enhancement set and are separated in a layer. You can have more layers if you want, although only one can be active. To define the enhancement set, use transaction SM30. For the Table/View enter BSPWDV_EHSET_DEF. Click on the Maintain button and then on the New Entries button. In the screen that appears, enter the enhancement set definition and save (Figure 4).

Figure 4

Settings for a new enhancement set

After you have defined it, assign the enhancement set to a client in the BSPWDV_EHSET_ASG table. Go to transaction SM30, enter BSPWDV_EHSET_ASG in the Table/View field, and click on the Maintain button. In the next screen, click on the New Entries button. In the screen that appears, enter the client in which the enhancement set should be active and the enhancement set you created in my example, client 140 and Z_PROJECT, respectively (Figure 5). Click on the save icon to continue. This activates your enhancements when you log on to client 140 and makes the enhancement the default for this client.

Figure 5

Settings for the assignment of the Z_PROJECT enhancement set to client 140

Step 3. Enhance the Component Now return to the Component Workbench. Enter BP_CONT in the Component field, enter Z_PROJECT in the Enhancement Set field, and press Enter. Click on the Enhance Component button. In the pop-up screen that appears, enter ZBP_CONT in the Assigned BSP Application field. Click on the enter icon, and then click on the Yes button in the next screen. This brings up the Input of Runtime Repository Storage Location screen. Repository.xml appears in the Page field. Leave this as is and click on the enter icon. You then see pop-up screens asking for Workbench requests. For this example, click on the local object in each Workbench request pop-up screen because you are not transporting the changes to another system. You then get a message that says you successfully created the enhancement and the title of the screen should contain the phrase Enhancement Set Z_PROJECT. To keep track of enhanced components, the system updates the tables that are part of the view cluster. Check out view cluster BSPWDVC_CMP_EXT to become familiar with how the system works (Figure 6). Go to transaction SM34, enter BSPWDVC_CMP_EXT in the View cluster field and click on the Display button. In the screen that follows, select the Z_PROJECT enhancement set (if there is more than one enhancement set) and double-click on Enhancement Definition on the left side.

Figure 6

The enhancement definition tells the runtime system to use the enhancement ZBP_CONT component instead of the standard BP_CONT component

The next screen shows you a list of enhanced components. If only one component exists in the list, you see the detail screen for that component, as shown in Figure 6. Otherwise mark the line with the BP_CONT component and double-click on Controller Substitutes on the left side.The screen that follows shows you a list of controllers that a custom controller has replaced. Besides the fact that the system uses this information to determine the correct controller at runtime, it is also a good way to get a complete view of all the parts of the CRM WebClient UI that have been enhanced with custom functionality. Step 4. Enhance the View Now you enhance the view you want to use. Go back to Figure 3 and right-click on BP_CONT/ContactNewDetailsEF. Select Enhance from the context menu and choose Local object for all the Workbench requests. The system displays a message that the enhancement was prepared successfully. Leave and re-enter the Workbench to avoid any errors. Figure 7 shows what has happened to the view.

Figure 7

Overview of the BP_CONT component in the Component Workbench

On the left side, the enhanced view is highlighted while the others are gray. On the right side, the implementation class of the ContactNewDetailsEF.do has changed to a custom class called ZL_BP_CONT_CONTACTNEWDETA_IMPL, which was generated by the enhance action. Also, the context implementation class has changed to a custom class called ZL_BP_CONT_CONTACTNEWDETA_CTXT. Double-click on the implementation class ZL_BP_CONT_CONTACTNEWDETA_IMPL. The Class Builder transaction is displayed for your class. In the Properties tab the custom class has the standard class as the Superclass. When we enhanced the view, the system created this class (ZL_BP_CONT_CONTACTNEWDETA_IMPL) as a subclass of the standard CL_BP_CONT_ CONTACTNEWDETA_IMPL. In the Methods tab, the system automatically redefines the methods WD_ CREATE_CONTEXT and SET_MODELS. The custom context class that the system generated when we enhanced the view ZL_BP_CONT_CONTACTNEWDETA_CTXT must be referenced in the custom view controller class. It is helpful to be aware of these redefined methods to gain an understanding of the effects of enhancing a view. Figure 8 shows the automatically redefined WD_CREATE_CONTEXT method.

Figure 8

WD_CREATE_CONTEXT method of the custom view controller class automatically redefined when you enhance the view

This method now retrieves an instance of the enhanced context class (instead of the standard context class). Also, the system adds the ZTYPED_CONTEXT attribute to the class. This attribute is important because through it you can access all the modified and newly created context nodes from the view. In the attribute screen of the Class Builder, you can see that this attribute was added as a protected instance attribute and that it is typed as a reference to the enhanced context class (Figure 9). Notice that the TYPED_CONTEXT reference is still there. The unmodified parts of the view use it to gain access to the unmodified context and its nodes.

Figure 9

The system adds attribute ZTYPED_CONTEXT automatically when the view is enhanced

Once again the system has updated the system tables as a result of enhancing the view. Look at view cluster BSPWDVC_CMP_EXT again with transaction SM34. The system added an entry for the controller substitution telling the runtime framework to use the enhanced view controller instead of the standard one.

Note In terms of classes inside a view, you always find an implementation class for the view,

an implementation class for the context, and an implementation class for each context node. A context node contains the data and is usually based on a Business Object Layer (BOL) entity. This is a layer of objects such as an account, a contact person, or an order that the CRM WebClient UI uses to access the underlying data that is actually stored in the database. The context holds all individual context nodes together. It instantiates the individual nodes and links them together when you have a dependency between two context nodes. The view instantiates the context. Step 5. Enhance the Context Node Next, enhance the context node so that you can add a field to the node. Right-click on BUILHEADER in Figure 7 and click on Regenerate GET_I methods. Click on Local object in each Workbench request that pops up. Look for a success message at the end, ignoring any other messages given there. Again, leave the Workbench and go back to the context node you are enhancing just to be certain that the display is correct. The context node class is now a custom class starting with a Z. In the main overview screen of the BP_CONT component, click on ContactNewDetailsEF.htm under View Layout and click on the Properties tab. Here, the Controller Class has changed to the new custom controller class ZL_BP_CONT_ CONTACTNEWDETA_IMPL. Next, click on the Page Attributes tab (Figure 10). The BuilHeader attribute, which refers to the context node, now contains the custom controller class in the Associated Type field.

Figure 10

Page attributes of the HTML page belonging to the view correspond to the list of context nodes

Go back to the main overview screen of the BP_CONT component and double-click on the custom implementation class of the context node ZL_BP_CONT_CONTACTNEWDETA_CTXT. This opens the Class Builder. In the Methods tab, notice that the CREATE_BUILHEADER method, which instantiates the BUILHEADER context node, has been redefined (Figure 11). The system has created this custom class starting with a Z as a subclass of the standard class when the context

node was enhanced. Instead of the standard context node class, the enhanced custom class is used for the context node.

Figure 11 Note

The system redefined the CREATE_BUILHEADER method when the BUILHEADER context node was enhanced

Earlier we pointed out the changes made as a result of enhancing the view. We showed the redefined method WD_CREATE_CONTEXT, but there was another redefined method called SET_MODEL. This method is responsible for making the context node data available to the Business Server Page (BSP) that is displayed to the user. Initially this method just calls the super method, which is the method of the original class. If you create a new context node (instead of enhancing an existing one as we are doing now), this method is extended to set the corresponding new page attribute referring to the new custom context node class. Step 6. Add the Field For our purposes, we want the field to be fully maintainable that is, it should be added to the create, edit, and display pages. Therefore, you need to make more changes to the underlying structures. If you expand the BUILHEADER context node in the main Workbench screen for this view, you see the custom context node controller class called ZL_BP_CONT_CONTACTNEWDETA_CN00. Double-click on the class name to go to the Class Builder transaction. In Class Builder, click on the Attributes tab. Notice the attribute called BASE_ENTITY_NAME with an initial value of BuilHeader (Figure 12).

Figure 12

Attributes of the custom context node controller class

To find out more about this BOL entity, go to transaction GENIL_MODEL_BROWSER. Enter ALL in the Component Set field and execute the program by clicking the execute icon or pressing F8. Look for BuilHeader under Root Objects and expand its Attribute Structure. This BOL entity is based on the Data Dictionary structure CRMST_HEADER_OBJECT_BUIL. When the new field is added to this structure, the BOL entity BuilHeader also has this new field as an attribute. The BUILHEADER context node is based on the BuilHeader BOL entity, so it also has this new attribute.

Note When you want to enhance a structure for a BOL entity, it may be better to use the Easy Enhancement Workbench (EEW) instead of manually extending existing Data Dictionary structures. If the EEW supports the corresponding business object, it is a consistent method of extending it. If you were to add a field to the CRM WebClient UI that should also be replicated to SAP ERP, or if it should be made available for SAP NetWeaver BI reports, then its better to use the EEW. All relevant structures are extended this way. For this example, we are adding the new field in an append structure of the CI_EEW_BUT000 structure. Note that this is a shortcut to keep the focus on the real topic of this article. EEW also uses this structure. Use transaction SE11 to create an append structure. Do the same for structure CI_EEW_BUT000_X, which the system uses to identify changed fields. The new field that we add to the append structure of the CI_EEW_BUT000 structure is called ZZFAVCOLOUR and has the data element ZCOLOUR. The ZCOLOUR data element has domain ZDCOLOUR, which is defined as a numeric type with one position. The domain has three possible values: Red, Yellow, or Blue (Figure 13). Perform these elementary Data Dictionary changes with transaction SE11. Do not forget to add the ZZFAVCOLOUR field to the append structure of the CI_EEW_BUT000_X structure. This is just an update indicator with component type BAPIUPDATE.

Figure 13

Create the domain ZDCOLOUR and add colors in the Value Range tab as possible values for the new ZZFAVCOLOUR field

Tip! You can also add the value help table via the design layer if you are familiar working with it. This approach does not require any custom classes on the CRM WebClientUI layer itself. After making these Data Dictionary changes, go back to the Component Workbench. Call up the BP_CONT component and navigate to the enhanced BUILHEADER context node of the BP_CONT/ContactNewDetailsEF view. Expand the BUILHEADER context node attributes to see the attribute STRUCT.ZZFAVCOLOUR in the list. Step 7. View Configuration Click on the Configuration tab to see the layout of the current view (Figure 14). In the configuration, you can add, remove, and reposition fields on the page. Add the new attribute STRUCT.ZZFAVCOLOUR here. We are going to change the layout with the default configuration key. Notice the title Standard Default Configuration in Figure 14. A configuration key is linked to a business role. A business role is linked to a user via the organizational model. The configuration concept allows you to create variations of the view and link them to different business roles, so that different users have different perspectives of the same view.

Figure 14

The standard default configuration of the BP_CONT/ContactNewDetailsEF view

First, click on the change icon. Then, click on Show Available Fields. The available context nodes, which contain the available fields if you expand them, are on the left side of the screen. Expand the BUILHEADER node and look for the new field Favourite Colour. Often it is easier to click on Show Technical Details to identify the field you need. The context nodes that are based on standard structures can contain a lot of fields and have similar or identical descriptions, so a mistake is easily made if you simply identify a field based on its description. Select //BUILHEADER/STRUCT.ZZFAVCOLOUR and click on the Language field. Then click on the add icon to add the field below the Language field. To set a label for the field, Alt-click on it. The field properties are now displayed on the right side of the screen, where you can set the label text and other layout properties of the field (Figure 15).

Figure 15

Attributes of the selected field

The system has recognized that the new field has a domain with possible values and renders it automatically as a drop-down list box. Note that this does not apply if you were to add a field to a context node manually, without changing the BuilHeader structure. Click on the Apply button after you are done and then close the field properties area. Click on the save icon to save the default configuration. Then log on the CRM WebClient UI and navigate to the contact person create page. It should look like Figure 16.

Figure 16

The Favourite colour field appears with the drop-down menu options

Enter some test values in the General Data block and pick a color. Click on the Back button and then on the Save button in the next page that displays an overview of the contact data. To verify that your color is saved, check table BUT000 with transaction SE16. Display the Field When you click on the Back button in the create page, the system navigates back to the contact person overview page. You want to show the new field here as well. To find out more about this view press F2. Be sure to click somewhere in the main section of the page containing the contact data first before you press F2. Otherwise you get the technical information about the surrounding component such as the navigation bar on the left. According to the information pop-up screen, the view is called ContactDetailsOV. Look up this view in the component browser (transaction BSP_WD_CMPWB). Enter component BP_CONT and enhancement set Z_PROJECT. Look at the available context nodes to see that the BUILHEADER node is also available in this view. Modify the configuration in the same manner you did in the previous view by adding the new field somewhere on the page, and then check out the result (Figure 17).

Figure 17

The Favourite colour field now also appears for existing contacts, but it is not rendered correctly

The field is there, but this is not how you want it to be. This is a display view but the system has rendered the field the same way as it did in the create page. We are going to solve this issue by adding a new field to the BUILHEADER node. This time we are not updating any underlying structures like we did in the previous steps. Instead, we add the field to this context only and write a GET method that retrieves the color text based on the favorite color value. Add the Field You need to enhance the BUILHEADER context node, but first you have to enhance the view. Go back to Figure 7 and right-click on the ContactDetailsOV view. Select Enhance from the context menu. Enhance the context node by right-clicking on it and choosing Re-generate GET_I methods. After the enhancements, the screen should look like what you see in Figure 18.

Figure 18

Overview of the enhanced BP_CONT/ContactDetailsOV view

As you can see, you have a custom view implementation class, a custom context class, and a custom context node class for the BUILHEADER node. Double-click on the custom context node class ZL_BP_CONT_CONTACTDETAIL1_CN00. In Class Builder, copy method GET_PREFIX to a new method called GET_ZZFAVCOLOUR_TEXT. Then replace all references to PREFIX with ZZFAVCOLOUR_TEXT inside the method. Generate the class and go back to the workbench by clicking on the Back button until you get there. In the view, go to the configuration by clicking on the Configuration tab. Click on the change icon, and then click on Available Fields. Expand the BUILHEADER node. The new field //BUILHEADER/ZZFAVCOLOUR_TEXT is now available at the bottom of the list. Add this field and go to its properties by Alt-clicking on it. Set a label text and mark the Read Only check box. Remove the ZZFAVCOLOUR field that you added before. Now go back to the new GET method GET_ZZFAVCOLOUR_TEXT in the Methods tab. This method returns the VALUE parameter to the CRM WebClient UI. Start by changing the reference to ZZFAVCOLOUR_TEXT to ZZFAVCOLOUR. This way, the correct value is retrieved from the BUILHEADER node. At the end of the method you can insert code to look up the domain text belonging to the current value. Then you simply overwrite the value parameter with the text of the domain value. Figure 19 shows what the code at the end of the method looks like.

Figure 19

Code fragment of the GET_ZZFAVCOLOUR_TEXT method

That should do it. Log on to the CRM WebClient UI and look up a contact person for which you have entered a color. It should look like Figure 20.

Figure 20 Change Details

The Favourite colour field now appears as a display field

Finally, press F2 to access the ContactDetailsEF view to add the new field here. Go to the component workbench and enter component BP_CONT and enhancement set Z_PROJECT. Look up the ContactDetailsEF view and double-click on it. Click on the Configuration tab to call up the default configuration. Add the

STRUCT.ZZFAVCOLOUR field of the BUILHEADER context node as you did in the first view. No coding is necessary here.

Boris Dingenouts is a senior SAP CRM consultant for the Dutch consultancy company Protg Consultancy. Boris has more than 12 years of consulting experience in SAP, with more than seven years in SAP CRM. Protg Consultancy is an SAP consultancy company focused on SAP CRM. You may contact Boris via email at [email protected]. Manuel Dekker is a senior SAP CRM consultant and founder of the Dutch consulting company Omnidev. He has 12 years of SAP consulting experience, of which the last seven years has been with SAP CRM. His main focus is the design and implementation of custom solutions. You may contact Manuel via email at [email protected].