Capturing Additional Service Request Information with Extensible Attributes

This chapter, which is relevant to all of the HTML-based modules, describes how you can set up your application to capture additional information in service requests using user-defined extensible attributes.

This chapter covers the following topics:

Extensible Attribute Overview

Extensible attributes permit you to capture additional information in service requests and cases. They are available in the Customer Support, Service Desk, and Case Management modules of Oracle TeleService.

Note: To capture additional information in service requests created in the Contact Center (Oracle Forms) you must use a different and incompatible architecture. See Capturing Additional Service Request Attributes in the Contact Center.

Extensible attributes, also called user-defined attributes, improve on the existing Descriptive Flexfield architecture on which they are built in the following ways:

Extensible Attribute Basic Concepts

Before you start creating extensible attributes, you must be familiar with a few concepts used in the user interface:

Value Sets

Value sets specify the list of values or drop-down list agents use to make their entries. Using value sets ensures agents enter only valid data.

You can enter the values for a value set directly in the interface, or generate the list from a database table with a PL/SQL query.

In addition, you can use a value set to specify the maximum number of characters the attribute can capture. The maximum 150. The default is 30 characters.

Note: To capture large amounts of text, use service request notes instead.

Value sets also have an alternate use. Instead of providing a list of values, you can use a value set to restrict the range of permissible values. For example, you can specify that agents can only enter numbers between 1 and 10 for the number of abandoned cars. The agents enter the number manually, rather than from a list, but receive an error message for entries outside that range.

Attributes and Attribute Groups

An attribute is the field that captures the additional piece of information.

You can specify the attribute to be rendered in different ways on the user interface. It can appear as a text box, a group of radio buttons, a drop-down list (called “poplist” in the user interface), a list of values, or a check box, depending on the information you wish to capture.

If agents are making an entry from a list, then you must specify the value set to be used to make the entry.

You must create an attribute as part of an attribute group.

You specify an attribute group to be multirow to enable agents to enter information about multiple items into the service request. For example, by creating a multirow attribute group for discarded furniture, agents can enter information on multiple pieces of furniture to be picked up on the same service request.

You can specify if the attributes in the attribute group are going to appear globally in all service requests or only in service requests of specific request types by mapping the group either to all service request types or to one or more individual service request types.

Pages

You specify how the attributes appear in the service request by creating different regions, called pages. Each page provides the heading under which the groups of attributes are displayed. You can display multiple attribute groups in one page. If you create multiple pages, you can specify the order in which they appear in the service request.

Where Extensible Attributes Are Displayed

Extensible attributes appear both in the Service Request page and the Advanced Search Page.

Service Request Page

The following image shows how the extensible attributes are displayed in the Service Request page. All attributes appear just below the Issues region.

Global attributes, those available for all service request types, are displayed first, followed by attributes mapped to the specific service request type.

The pages and the attribute groups provide headings that organize the attributes on the page. The image below highlights some of these by number:

  1. Region headings, such as “Item Location” and “Vehicle Details”, come from the entries you make during page setup (the Display Name field for the page).

  2. Attribute group headings, such as “Location Details”, come from the attribute group (the Display Name field for the attribute group).

    You can choose to omit this level of heading on the page by making the wording of the attribute group heading identical to the page heading during setup.

    Asterisks mark attributes you have designated as required.

  3. You can set up attributes of different kinds. This is an example of a multirow attribute group. All of the attributes in the attribute group appear in one row. To add additional rows, agents click on the Add Another Row button which is rendered automatically.

    the picture is described in the document text

Advanced Search Page

Agents can also use the extensible attributes in advanced searches available from the Dashboard page.

Agents can add any indexed attributes you have created as search criteria by using the Add Attributes drop-down box in the Service Request Attributes region (see item identified by number 1 in the advanced search page image below).

The attribute displays with its attribute group display name hyphenated in front (2), for example: “Vehicles for Towing- Make”.

Agents can add any non-indexed attributes they want for searching in the Service Request Additional Attributes region below (3), for example: “Location Details - Location”.

the picture is described in the document text

Number of Supported Attributes

Each service attribute group can have as many as 125 attributes:

By creating additional attributes groups, the application effectively gives you the ability to capture an unlimited number of additional service request information.

Personalization

You cannot use the personalization feature of the Oracle Applications Framework to move or modify individual attribute regions, headings, or fields. You must use the extensible attributes architecture itself to do so.

The only permitted personalization is moving or hiding the region where extensible attributes are displayed.

Extensible Attribute Architecture

The capture of additional service request attributes is based on the user-defined attribute architecture developed for Oracle Product Lifecycle Management.

You can obtain additional details about using this architecture by referring to the Attributes and Functions chapter of the Oracle Product Lifecyle Management User's Guide and the Oracle Product Lifecyle Management Implementation Guide.

Oracle TeleService supports all of the architecture features except for attribute security. The data security for extensible attributes is the same as for all other service request information: Any user who has access to the service request can also access the information entered in the additional attributes.

Oracle TeleService extends the architecture by providing the mapping function between attribute groups and service request types. Information on this feature is covered by this guide exclusively.

Extensible Attributes for Customers and Associated Parties

You can use the same extensible attribute architecture to capture additional information for database objects other than service requests.

If you are using Case Management, you can use extensible attributes to capture information about the parties associated with a case. For example, an investigative agency may want to capture the height, hair color, and eye color of suspects in a case. The setup of attributes for associated parties is very similar but not identical to the setup of service request attributes. (See Setting Up Associated Party Extensible Attributes.)

The Trading Community Architecture customer model also uses the same extensible attribute architecture. This means that you can capture additional attributes with customer data. This way the information is visible across all Oracle E-Business Suite applications rather than just in Oracle TeleService.

A social services agency may want to capture details about the past criminal history of its clients with the client record, for example. A retailer may want to capture the garment sizes and color preferences for customers to aid in marketing efforts.

Setting Up Service Request Extensible Attributes

Use this overview to guide you through the process of setting up the capture of additional information for service requests. Follow the references in each step for a general procedure and an example.

To capture additional service request information using extensible attributes

  1. If agents are going to be using lists of values or drop-down lists to make their entries, then create the value sets.

  2. Create the attributes themselves as part of an attribute group.

  3. Specify which attribute groups you want displayed globally or map them to specific request types where you want them to appear.

  4. Optionally, create custom functions to perform calculation based on agent entries, for example, calculating the total number of items entered into the service request. See Creating Custom Functions for Attributes.

  5. Create the regions where the attributes are displayed in the Service Request page.

Setting Up Value Sets

Use this procedure to set up lists of values users will use to enter data in an attribute.

To set up value sets

  1. Navigate to Setup, Definitions, Request Extensible Attributes, Value Sets.

    The Maintain Value Sets page appears.

    the picture is described in the document text

  2. Click Create.

    The Create Value Set page appears.

  3. Enter a unique name and an optional description. Users do not see either of these entries.

  4. If the extensible attribute entries are going to be numbers:

    1. Choose Number from the Data Type drop-down list.

    2. Enter the maximum field size of up to 150 characters in the Maximum Size field. The default is 30 characters.

    3. Optionally enter a range for valid values.

  5. If the information to be captured is a date, then:

    1. Choose Standard Date or Standard Date Time from the Data Type drop-down list. This selection captures time information as well.

    2. Optionally enter a range for valid dates. You can use $SYSDATE$ to represent the current date and time.

  6. If the information to be entered is a character string, then:

    1. Choose Char from the Data Type drop-down list.

    2. Enter the maximum field size of up to 150 characters in the Maximum Size field. The default is 30 characters.

  7. Choose the validation type:

    • To have agents make the entry in the field manually, choose None.

    • If agents are going to be choosing from a drop-down list or a list of values and you plan to enter the values for the list manually, then choose Translatable Independent.

    • If the list of values is generated dynamically from a database table, for example, if the attribute is dependent on another attribute, then choose Table. See Example of Dependent Attribute Setup.

      You must enter a PL/SQL query for the table from which you want to generate the list. You must be familiar with the application table structure and know PL/SQL before using this option.

  8. If you are having agents choose from a list, then specify if that list is to be a drop-down list, by choosing the Pop-list radio button, or a list of values.

  9. Click Update.

  10. If the list is not generated from a table, then you must create the list value by value manually by clicking Create in the Values region.

    You can order the values in the list using the Sequence field. To add additional entries, click Add Another.

    If you have chosen Translatable Independent, then agents see the descriptions you enter in the translated value for the language you are logged in.

Setting Up Attributes and Attribute Groups

Use this procedure to create the extended attribute fields that capture the additional service request information. You create extended attributes as part of an attribute group. Attribute groups organize attributes under a heading on the service request page. By mapping attribute groups to service request types, you specify where the attributes appear.

Prerequisites:

To have agents choose values from a list or to restrict entries to a range, set up a value set first. See Setting Up Value Sets.

To set up attributes and attribute groups

  1. Under the Service responsibility, navigate to Setup, Definitions, Request Extensible Attributes, Attribute Groups and Attributes.

    Note: If you want to create attributes for associated parties, you must instead navigate to Setup, Definitions, Associated Parties for Case Management, Party Roles Extensible Attributes, Attribute Groups And Attributes.

    The Attribute Groups page appears.

    the picture is described in the document text

  2. Click Create.

    The Create Attribute Group for Type Flexfield page appears.

    the picture is described in the document text

  3. Enter an internal name and a display name. The display name is the title the agent sees above the groups of attributes.

    Note: If you do not want to have two separate heading for the page and for the attribute group, then make sure the Display Name entry is the same for the attribute group as for the page.

  4. To permit entry of multiple rows, select the Multirow check box. See Example of Multirow Setup.

    Note: The data security at the extensible attribute level is not supported in this release. The data security for extensible attributes is the same as for all other service request information: Any user who has access to the service request can also access the information entered in the additional attributes.

  5. Click Apply and Add Attributes.

    The Create Attribute page appears.

    the picture is described in the document text

  6. Enter a unique internal name and the display name. The display name is the field name the user sees.

  7. Specify the order the attribute appears in the page by entering a number in the Sequence field.

  8. Choose a data type. If you have created a value set for use with this attribute, then the data type must be the same as that of the value set. The Translatable Text data type is not supported.

  9. Enter "%" (the percent sign) in the Column field and click the List of Values icon. The application displays the available columns. Choose any column. After you use a column, it no longer appears on this list.

  10. Make sure that Enabled is selected.

  11. If entry in this field is required, then select Required. Required fields are indicated on the page with an asterisk.

  12. Specify how the field appears on the page by making a choice from the Display As drop-down list:

    Which values are available to you is determined by the data type you have specified:

    • Checkbox: Displays a check box. The unselected checkbox stores the value of N. Selecting a check box stores a value of Y. If you enter Y in the default field, the check box is selected by default.

    • Dynamic URL: You can use this method to display a URL with service request parameters, such as the incident location, which the agents can use to access Internet services, to obtain a map of the area, for example.

      To use this feature you must add parameters, such as street=$StreetName$&postalcode=$ZipCode$, to the Dynamic URL field.

      However, agents can only click on this URL in the read-only service request page. In the service request creation and update pages, the URL displays in an entry field, so agents must copy and paste it into a separate browser window. For this reason, this display method is of limited use for service applications.

    • Hidden: Choosing this value does not display the attribute in the user interface. Use this selection to store a value of a function, for example.

    • Radio Group: Displays a group of radio buttons corresponding to the values in the value set you specify. You must specify a value set with discrete set of values that you have entered.

    • Static URL: This method displays a URL in the service request page, but agents can only click on it in the read-only service request page (displayed only for agents who do not have update access). In the service request creation and update pages, the URL displays in an entry field, so agents must copy and paste it into a separate browser window. For this reason, this display method is of limited use for service applications.

    • Text Area: Displays a bigger text area. You are still limited to the 150 character maximum.

    • Text Field: Displays a text field. If you specify a value set, then the field displays with a drop-down list or a list of values indicator.

  13. Selecting the Indexed check box indexes the field in the database for faster searching. If selected, the attribute appears among the most frequently used attributes at the top of the Advanced Search page. For an example of how this page displays for agents, see Advanced Search Page.

    Note: Limit the number of indexed attributes to only those fields frequently used for searching. Adding indexed fields affects your database performance.

  14. If you have created a value set for this attribute, then enter it in the Value Set Name field.

  15. Optionally, enter the Default Value.

  16. If you are making this service request attribute group to be multirow, then each row agents enter must be unique. You must specify which attributes specify unique entries:

    1. Click Maintain Unique Key in the Attribute Group Details page.

    2. Use the arrow buttons to specify the attributes by moving them from the Attributes column to the Unique Key Attributes column.

    3. Click Apply when you are done.

Specifying the Service Request Types Where Attributes Appear

For your attributes to be visible to the user, you must map the attribute groups to which they belong to either all service request types or to a specific service request type. You can map the same attribute group to multiple service request types.

Prerequisites:

You must create the attributes and attribute groups first. See Setting Up Attributes and Attribute Groups.

To associate attribute groups to service request types

  1. Under the Service responsibility, navigate to Setup, Definitions, Request Extensible Attributes, Associate Attribute Groups.

    The Associate Attribute Groups page appears.

  2. Choose the service request type or All Request Types from the Classification drop-down list.

    Mapping attribute groups to All Request Types makes them visible in all service requests regardless of service request type.

  3. Click Add Attribute Groups.

    The Add Attribute Groups to Classification page appears listing all of the attribute groups.

  4. Use the Search field to narrow down the list, if necessary.

  5. Select the attribute groups you wish to add and click Apply.

Creating the Regions (Pages) Where the Attributes Display

Use this procedure to create the region where the attributes are going to be displayed. The setup user interface uses the term "page" instead of region.

If you are exposing attributes from multiple attribute groups in a service request type, you can choose to display the attributes under one heading by creating just one region (page) or you can create multiple regions so the attributes appear with their own headings.

Suppose, for example, you create two attribute groups: one to capture information about a driver and the other to capture information about the vehicle they are driving. You can display both the attribute groups in one region under one heading, “Car and Driver” or display them in two separate regions under separate headings “Car” and “Driver”.

Prerequisites:

To associate attribute groups to service request types

  1. Under the Service responsibility, navigate to Setup, Definitions, Request Extensible Attributes, Page Associations.

    The Service Request Extension Pages page appears.

  2. If you are creating pages for attribute groups visible globally, then choose All Request Types from the Classification drop-down. Otherwise, choose the service request type where the attributes are to be displayed.

  3. Click Create Page.

  4. The Create Extension Page page appears.

  5. Enter a the text for the heading for the region in the Display Name field.

    Note: If you make the wording exactly the same as the display name for the attribute group, the application displays only the page heading.

  6. Enter a unique internal name. Agents do not see this name.

  7. Enter a sequence number. If you are displaying attributes in multiple regions, the sequence number determines the order in which the regions are displayed in the service request user interface.

  8. Click Add Another Row.

  9. Use the list of values to enter the attribute group(s) you wish to add to this page. Your entry in the Sequence field determines the sequence in which the attribute groups display on the page.

    Note: The list of attribute groups is filtered by the mapping you have created previously.

Creating Custom Functions for Attributes

You can create custom functions for making calculations based on entries in attributes. For example, you can add a Calculate Total button that sums the entries in a multirow field and stores the result in another attribute.

A function can be a Java method or a PL/SQL function. An application administrator must first implement the function either in the database, if it is PL/SQL stored procedure, or for Java functions, the function can be created and saved in a directory that is part of the Java classpath.

The Create Function page is available under the Service responsibility by navigating to Setup, Definitions, Request Extensible Attributes, Functions.

The button or URL that triggers the function is called an action. You create an action after you have mapped the attribute groups to service request types. Navigate to Setup, Definitions, Request Extensible Attributes, Attribute Group Associations and click Update Actions.

For more information, see the Implementing User-Defined Functions section in the Oracle Product Lifecyle Management Implementation Guide and the Creating User-Defined Functions section in the Oracle Product Lifecyle Management User's Guide.

Example of How Extensible Attributes Are Used in Practice

This section outlines how a city government agency responsible for disposing of solid waste, including the towing of abandoned vehicles, can use extensible attributes to capture the additional information it needs about the vehicle to be picked up.

In addition to the address, the agency must know the location of the items to be picked up. They can be on the street, in a drive way, or on the sidewalk.

Because this information must be captured for all items, the agency creates a global extensible attribute. See Example of Global Extensible Attribute Setup.

For Abandoned Vehicles, the agency must know the vehicle's make, model, and color, information that will determine the type of tow truck it must send.

Because this information must be captured for vehicles, but not for furniture, or appliances, the agency sets this attribute to display only for the Abandoned Vehicles service request type.

In addition, the agency must make the list of values for the model dependent on the entry the agent makes for the car model. This way agents see just the models relevant to the make they have entered. This setup is discussed in Example of Dependent Attribute Setup.

Because the agency may have to pick up more than one vehicle at a single address, it must set up the vehicles to capture multiple rows. See Example of Multirow Setup.

Example of Global Extensible Attribute Setup

An agency wants to capture the location of items to be picked up. As this information must be captured for all service requests, the agency sets up a global attribute.

Example of Value Set Setup for Item Location

The agency wants to enter the location of the items to be picked up using a list of values to ensure the locations are standard for reporting purposes:

  1. On the Create Value Set page, make the following entries:

    • Value Set Name: ITEM_LOCATION

    • Validation Type: Translatable Independent

      This validation type makes it possible for you to display each value in the list how you want the agent to see it.

    • Display Type: Poplist

    the picture is described in the document text

  2. Click Apply and Continue, and enter the values one by one:

    • On sidewalk

    • In drive way

    • In the street

    Note that the Translated Value field is where you enter the wording the agent will see.

    The image below provides an example of one of the values:

    the picture is described in the document text

Here is what the final value set looks like:

the picture is described in the document text

Example of Attribute Group Setup for Item Location

Here is an example of how you can set up a simple attribute to capture additional details about item location.

Example of Item Location attribute group setup:

  1. On the Create Attribute Group for Type Flexfield page, enter the following:

    • Internal Name: Itemloc

    • Display Name: Item Location

      This provides the heading agents see for the attribute group in the service request.

    The following screen image shows the setup:

    the picture is described in the document text

  2. Create the attribute.

    There is only one attribute to create for this attribute group: a text field where agents will make an entry by using a drop-down list from the value set Item_Location.

    Make the entries as follows:

    • Internal Name: Location

    • Display Name: Location

      This is the name that appears as the label for the drop-down list (poplist).

    • Sequence: 10

      The number you enter here is unimportant as there is only one attribute in this attribute group.

    • Tip: <Enter an optional tip text here. The formatting is constrained by the length of the field itself. If your tip is long, it will wrap to fit the width of the field.>

    • Data Type: Char

    • Column: Choose any available column.

    • Enabled check box: Selected

    • Required check box: Selected

      You want to require agents to choose a location.

    • Display as: Text Field

    • Indexed check box: Unselected

      You do not need to index this field as agents are not going to use it for searching.

    • Value Set Name: Itemloc

      This is the internal name of the value set you created.

    The image below shows the entries:

    the picture is described in the document text

Example of Mapping Attribute Group to Service Request Types

Because you want to capture the location in all request types, you must map the attribute group top all request types.

Example of how to map an attribute group to make it global:

  1. Navigate to Setup, Definitions, Request Extensible Attributes, Page Associations.

  2. Choose All Request Types from the Classification drop-down list.

  3. Add the Item Location attribute group.

    The following image shows the completed mapping:

    the picture is described in the document text

Example of Page Setup to Display an Attribute Group

You must create the region of the service request page where the attribute will be displayed.

To create a page for the Item Location attribute group:

  1. Navigate to Setup, Definitions, Request Extensible Attributes, Page Associations.

    the picture is described in the document text

  2. Click Create Page to display the Create Service Request Extension Page.

  3. Enter the following:

    • Display Name: Item Location

      The text you enter in this field appears as the region heading. If the wording is exactly the same as the Display Name of the Attribute group including capitalization, then the application displays only one heading for this region instead of two.

    • Internal Name: Item_Location

    • Sequence: 10

      The number you enter here is unimportant as you are capturing the information from only one attribute group.

      the picture is described in the document text

    The resulting Item Location region appears in the Service Request just below the Issue region. (Note that, because the Page and Attribute Group display names are the same, no attribute heading appears):

    the picture is described in the document text

Example of Multirow Attribute Setup

Because the agency may need to tow more than one vehicle from a given location at a time, the Abandoned Vehicles attribute group must be made multirow.

The application requires that each row agents enter must be unique. For example, an agent cannot enter the two following identical rows:

Make Model Color
Ford Taurus White
Ford Taurus White

For this reason, you must create a third attribute, “No. Items”, to cover the possibility that there will be more than one car of the same make, model, and color. If multiple cars of the same make and models or two or more cars of unknown model and make must be towed, then the agent enters the number in this field.

You can default “1” in this field, so that agents need not make an entry every time:

No. Items Make Model Color
1 Ford Taurus White

To set up the multirow entry:

  1. Create the three value sets: Make, Model, and Quantity.

  2. Create the attribute group Vehicle_Details, with the Multirow check box selected.

    The following screen image shows the attribute group setup.

    the picture is described in the document text

  3. Click the Maintain Unique Key button (highlighted in the image above) and specify which fields will be used to guarantee unique entries.

    This is accomplished by moving the attributes to the Unique Key Attributes column using the arrow keys. In this case, the unique key attributes are Make and Model (see the screen image below).

    the picture is described in the document text

Example of Dependent Attribute Setup

This topic describes how you can make the entry of one attribute, such as the model, dependent on the entry of another, the vehicle make.

To set up the entry of one attribute to be dependent on the value of another:

  1. Create a database table that stores the relationships between the two attributes, in this example vehicle make and model. The database table VEHICLE_MODEL contains the following data:

    Make Model
    Toyota Tercel
    Toyota Camry
    Honda Civic
    Toyota Unknown
    Honda Accord
    Honda Unknown
    Ford Focus
    Ford Mustang
    Ford Unknown
    Unknown Unknown

The “Unknown” values permit agents to make an entry even if they don't know the make and model.

Note: If you do not want to create new tables, you can add the data into the FND lookup table.

  1. Define a value set Vehicle_Make_Values as a poplist with the following values:

    • Toyota

    • Honda

    • Ford

    • Unknown

  2. Define an attribute group called Vehicle_Information.

  3. To the attribute group Vehicle_Information, add the attribute Vehicle_Make (using the internal name Vehicle_Make) and set the value set to Vehicle_Make_Values.

  4. Define the dependent values set Vehicle_Model_Values:

    Field Value
    Name Vehicle_Model_Values
    List Type List of Values
    Validation Type Table

    For the Validation Table Information enter:

    Field Value
    Table Name VEHICLE_MODEL
    Name (Value Column) Model
    Type (Value Column) Char
    Size (Value Column) 30
    Where Clause make=:$ATTRIBUTEGROUP$.Vehicle_Make

    Note that you can add any number of conditions to the Where Clause and that “$ATTRIBUTEGROUP$” is a reserved word.

  5. Add the attribute Vehicle_Model to the Vehicle_Information attribute group and set the value set to Vehicle_Model_Values. The sequence of this attribute must be larger than that of Vehicle_Make attribute.