Customizing the APM User Interface

Objectives

After completing this lesson, you will be able to:

Customize Menus.
Create an Entity Field.
Customize Field Labels, Codes, and Dropdown Lists.
Define field validations and dependencies.
Configure forms.

Introduction to Customizing the APM User Interface

Select the link 'Field Labels, Codes and Dropdown Lists' to get more information.

In this lesson, we’ll cover many of the ways you can customize the user interface in APM during implementation. We’ll cover:

Customizing menus
Customizing field labels, codes and dropdown lists
Managing code types and code values
Defining field validations
Defining field dependencies
Configure forms
Managing field styles

Customizing Menus

The Custom Menu feature allows Administrators to rename, move, add, or remove Portals, Tabs, and Menu Items. This feature can be found in the Administrator portal under Configuration → Custom Menu Search.

The video Customizing Menus in SAP Agent Peformance Management shows the detailed steps to customize the menus and submenus.

Select the link 'Customizing Menus in SAP Agent Performance Management' to get more information.

ExerciseStart Exercise

Exercise: Customize a Form Name and Field Label

Business Example:

By default, the Manager portal contains the Producer form, but your organization prefers this menu to display as Agents, and the Producer ID field on the form to display as Agent ID. In this exercise, we will make these updates.

Steps

Change the name of the Producers tab to Agents.
1. From the Manager portal, select Producers → Producers.
2. Select Producers title at the top of the window.
3. In the English column, enter Agents.
4. Select Save, then Close.
Relabel the Broker ID field on the search form to Agent ID.
1. Select the Broker ID field label on the search form.
2. Select Labels
3. In the English column, enter Agent ID on all three rows.
4. Select Save.
Relabel the Producer ID field on the results form to Agent ID.
1. Open any Producer record.
2. Double-click the Producer ID field label.
3. Select the Labels item on the left pane.
4. In the English column, enter Agent ID for all three rows.
5. Select Save, then Close.

Customizing Fields and Dropdown Lists

Another part of customization involves the management of the various dropdown lists and their values, assigning the lists to a field, and adding the field to search and display forms. In this lesson, we will cover each of these topics from beginning to end, including Entity Fields, Codes, Entity Edits, and Field Defaults. Once we have created these objects, we will configure a form to include the new fields.

Entity Fields

Any piece of data in APM is referenced as an entity. An entity can refer to a field, record, form, table, and many other items.

The Entity Fields functionality allows you to add user-defined fields to existing entities. Fields added by the Entity Fields functionality have the same functionality as standard out-of-box fields. For example, the fields are available in Form Configuration, Entity Edits, Field Defaults, Expressions, Security, Entity Indexes, and so on.

ExerciseStart Exercise

Exercise: Create Entity Fields

Business Example

In this exercise, we will create two entity fields: Producer Birth Date and Favorite Color.

Steps

Create a broker entity field called BirthDate
1. In the Portal menu, navigate to Administrator → Entity Configuration and select Entity Field Search.
2. Select Create.
3. Set the Entity Name to 'Broker'.
4. Set the Field Name to 'BirthDate'.
5. Set the Value Type to 'Date'.
6. Select Save.
7. Select Activate.
Create a broker entity field called FavoriteColor.
1. Use the link at the top of the page to return to the Entity Field Search page.
2. Choose Create.
3. Set the Field Name to 'FavoriteColor'.
4. Set the Value Type to 'Text'.
5. Select the Maximum Length radio button.
6. In the Maximum Length field, enter '10'.
7. Select Save.
8. Select Activate.

Code Types and Code Values

A Code Type is a pre-configured list of possible values that can be assigned to a specific field. Code Values define the stored and displayed values for code types. Note that field code type can only be applied to an out of box field and not to user defined fields.

There are three different code types:

System Defined Code Types with System defined values only allows users to change the displayed value, but are otherwise static.
System defined code types with user defined values allows you to define both stored and displayed values.
Finally, Client defined code types with client defined values can be completely customized.

For each of these code types, you can define the display type and display order.

Select the link 'Configuring Codes in APM' to get more information.

Exercise: Create a Code Type to hold a list of colors

Business Example

In this exercise, we will configure a dropdown list that allows us to select a favorite color. We will then use Code Values to add values to the list.

Steps

Create a Code Type called Color.
1. From the Administrator portal, select Configuration - Code Type Search.
2. Select Create (+).
3. Enter the Code Type ID: Color.
4. Set the Display Order and Display Type to 'Display Value'.
5. Change the Stored Value Type to 'Text'.
6. Set the maximum length to '10'.
7. Select Save.
8. Select Activate.
Add Code Values to the Colors code type.
1. Scroll down to Related Entities.
2. On the Header row, select Add (+).
3. In the Stored Value field, enter Red.
4. In the English field, enter Red.
5. Select the Save icon on the Related Entities header.
6. Repeat these steps to add rows for Blue and Green.
7. Select Save.
8. Select Activate.

Field Defaults

The Field Defaults process allows you to define a default value for a field, which is used if the field is not populated when the record is created. Field Defaults are managed from the Administrator Portal under Entity Configuration – Field Defaults.

For example, as shown in the image below, if the Full Name field is not populated, the field will be populated with a concatenation of First Name, Middle Name, and Last Name.

Field Validations and Dependencies

Entity Edits for Field Validation

Entity edits allow you to create user-defined validations on fields. Use entity edits when you want to create any type of validation on user defined fields, including drop down lists.

When you create an entity edit, you will add an expression to define the validation using Groovy.

Entity Edits are managed from the Administrator Portal under Entity Configuration – Entity Edits.

When configuring an entity edit, the expression must return a Boolean result. The result can return a warning, which allows the user to save the record, or an error, which must be corrected before the record can be saved.

The image below shows an example of an entity edit that requires both the First Name and Last Name fields on the Broker record if the Individual box is checked.

Field Dependencies

The Field Dependency functionality allows you to define relationships between specific fields for an entity and control the valid combinations of field values between the fields. This ensures that valid combinations of field values are used regardless of whether a record is being created or updated in the user interface, a posting process, or any other method. Field Dependencies are managed from the Administrator Portal under Entity Configuration – Field Dependency Search.

The image below shows an example of a field dependency. If the Broker Type is Account Executive, Account Manager, or Agent Manager, the only Broker Subtype that can be selected is Agent. If the Broker Type is Agency, the Broker Subtype can be IMO, FMO, or NMO.

Configuring Forms

In this section, we’ll focus on configuring forms. When configuring forms, you can indicate which fields and links are available on a form, as well as the order in which they appear.

You can configure both search and results forms for each type of entity in APM. Search forms are the section of the screen that we use to filter the results. Results forms are the resulting forms that contain the data fields.

For example, the Producer Search form appears like the image below by default. In this case we are searching for a producer with the ID MM-001.

Once the producer has been found and opened, the form looks like this:

The possibilities for customizing forms are extensive, but some of the changes you can make include:

Indicating which fields to include on the search form
Indicating the order in which fields appear on the form
Pre-defining the sort order of records in the search results
Defining the way the form behaves when it’s opened
Setting other form controls such as the number of rows shown on each page.

You can configure search forms to display differently by individual user, for all members of a security group, or globally for all users.

Sections

To make your forms more readable, you can group fields and links into sections. You can also create new sections, modify section labels and layouts, and indicate whether a section is collapsible.

Why are sections useful? Let’s say we want to display contact information, such as phone and email, for each producer. The first image below shows these fields at the bottom of the form.

Moving the fields to a section makes it much easier to visually emphasize the contact fields and set them apart from the rest of the producer detail:

To configure a detail form:

Open a detail form such as Producer Master Detail.
From the Tools menu in the upper right, select Configure.
Select the Form ID (Broker Master).
Select the Configure icon in the Form Customizations section.
Drag and drop any fields or sections to the form and select Save.

To see a demonstration of the process of configuring forms, see the video Configuring Forms.

Select the link 'Customizing the UI Part 3 - Configuring Forms' to get more information.

Hint

For entity fields to appear after configuring a form, you need to run the SynchDB process. To do this, go to Administrator – Tools – Database, select Synchronize Database, and select Run.

Field Styles

Field Styles allow you to manage the attributes of a field, to change how it is displayed on a form. For example, you can alter the default size of a field on the form, or alter the background color of a field to visually alert the customer to a special characteristic of the field.

The images below show two custom fields, Birth Date and Favorite Color, before and after customizing the field styles.

When you create a field style, you can select whether the field style applies to a specific form, such as Broker or Address, or whether it is global. Field Styles can be found in the Administrator portal under Entity Configuration – Field Styles.

Select the link 'Entity List Objects and Field Styles' to get more information.

Configure the Producer Detail Form

In this exercise, we will add the two user defined entity fields, BirthDate and FavoriteColor, to the Producer Master Detail, and format the fields to display correctly.

Since we added two entity fields, they will not appear in the form configuration until we synchronize the database.

ExerciseStart Exercise

Steps

Run SyncDB to synchronize the database.
1. From the Administrator portal, select Tools.
2. Under the Database sub-menu, select Synchronize Database.
3. Select Run.
Add the ProBirthDate and ProFavoriteColor fields to the Producer Master Detail form.
1. From the Manager portal, open Producers – Agents.
2. Select Search to display the list of agents.
3. Open any agent record.
4. Select the ellipse (…) in the upper right and select Configure.
Select the Form ID from the list of forms.
Select Configure.
1. Find the BirthDate field in the Components list on the left.
  The Form Builder is displayed.
2. Drag BirthDate to the bottom of the Agent Information section.
3. Drag FavoriteColor to the right of the BirthDate field.
4. Select Save, then Close.
5. Save and close the form detail dialog box.
  Note
  BirthDate and FavoriteColor fields now appear under the Broker Information.
Change the labels to Birth Date and Favorite Color.
1. Double-click the label next to the BirthDate field.
2. Select Labels.
3. Enter Birth Date in the English column on all three rows.
4. Select Save.
5. Repeat these steps to change the FavoriteColor label to Favorite Color.
Close the Configure window and the Form Detail window.
Change the FavoriteColor field to use the dropdown list showing the entity values.
1. Select Administration → Entity Configuration → Entity Field Search.
2. Search for the Entity FieldFavoriteColor.
3. Select Reopen.
4. Change the Value Type to Code.
5. From the Code Type list, search for and select Color.
  Note
  We created this code type list in the previous exercise.
6. Select Save, then Activate.
Use a Field Style to change the width of the FavoriteColor field.
1. Open Adminstrator → Entity Configuration → Field Styles.
2. Select Add (+).
3. Select the Entity Name: Broker.
4. Select the Field Name: FavoriteColor.
5. Leave the Form ID blank.
6. Select a Custom Style: StandardDropDown.
7. Set the Field Width to 100.
Select Save.

Next lesson