Release 12.

Flexible Attributes Guide

M20229-00E12000000 July 2003

 19952003, Amdocs. All Rights Reserved. Amdocs Confidential This manual and the software described herein are subject to your Amdocs Software License and are copyrighted with all rights reserved. This manual and the software may not be copied, in whole or in part, without written consent of Amdocs, except as permitted by your Amdocs Software License. The information in this manual is furnished for informational use only by authorized persons, is subject to change without notice, and should not be construed as a commitment by Amdocs. Amdocs assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. The trademark and service marks of the respective Amdocs companies, including the Amdocs mark and logo, are the exclusive property of such companies, and may not be used without permission. All other marks mentioned in this material are the property of their respective owners.

For technical assistance, visit http://clearanswer.clarify.com to submit a case at any time.

Contents
About this guide Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to use this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 1 Flexible Attributes Overview Understanding Flexible Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Using Flexible Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Definition and Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Flexible Attribute Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Understanding Flexible Attributes Architecture . . . . . . . . . . . . . . . . 10 Understanding the Flexible Attributes Data Model . . . . . . . . . . . 10 Accessing Flexible Attributes Using ClarifyCRM Business Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Accessing Flexible Attributes Using ClearBasic . . . . . . . . . . . . . . 11 Appendix A Flexible Attributes Data Model Reference Flexible Attributes Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flexible Attributes Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flexible Attributes Metadata Tables . . . . . . . . . . . . . . . . . . . . . . . . Flexible Attributes Definition Table . . . . . . . . . . . . . . . . . . . . . Flexible Attributes Template Table . . . . . . . . . . . . . . . . . . . . . . Direct Relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 14 14 14 16 16 5 5 5 6

About this guide

Audience
This guide is intended for system administrators or developers responsible for defining data requirements for ClarifyCRM applications.

How to use this guide

This guide contains the following sections:

Chapter 1, Flexible Attributes Overview provides a conceptual overview of Flexible

Attributes.

Appendix A, Flexible Attributes Data Model Reference describes the ClarifyCRM data model
extended with Flexible Attributes. The glossary defines Flexible Attributes terms used in this guide.

Conventions
These special formats are used:
NOTE: Provides additional information that is useful but not always essential.

More Information: Refers you to other sections of this guide or to other documents for more information.

IMPORTANT: Highlights key considerations to keep in mind.

CAUTION: Highlights important situations that could potentially damage data or cause system failure.

TIP: Highlights guidelines and helpful hints.

Related documentation

Related documentation

Setting Up the ClarifyCRM System Business Objects Programmers Guide Core Business Objects Reference Guide ClearBasic Programmers Guide Process Manager Administration Guide

About this guide

Chapter 1

Flexible Attributes Overview

In This Chapter Understanding Flexible Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Using Flexible Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Understanding Flexible Attributes Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Understanding Flexible Attributes

Understanding Flexible Attributes

A database is made up of entities (also known as tables) that define objects in which data can be stored and manipulated. An entity consists of a set of attributes that describe the individual pieces of data that make up each instance (or row) of that entity. For example, an entity that defines employees might have attributes that include first name, last name, job title, and department.
Table 1 Example of an Employee Entity First Name John Mary Joe Last Name Smith Jones Williams Job Title President Vice President Director Department Sales Marketing Engineering

Standard attributes are static definitions of the entities in a database. They are a part of the database schema that defines the entire database. If you want to add a new standard attribute to further define an existing entity, you must change the database schema. Changing the database schema (especially in a production environment) can be very problematical, as it is typically time consuming, disruptive, and requires technical expertise. Flexible attributes are data items that can be defined for an entity without the need to change the database schema. Each flexible attribute is stored in a row, in a separate table, related to the "owning" table. Each attribute is stored as a row in this generic "attribute" table, and related to the row to which it belongs. A typical use for flexible attributes might be for product definition, where various products have different sets of attributes. For example, a car might have engine size, color, and number of doors, whereas a computer might have CPU, memory, and disk size. Table 2 provides a simplified example of a set of flexible attributes for a generic product entity, including entries for two different products (cars and computers).
Table 2 Sample Flexible Attributes For a Product Entity Name Engine Size Engine Size Color Color Doors Doors CPU CPU CPU Memory Memory Disk Disk Value 502 350 Red Green 4 2 486 586 686 512KB 2GB 20MB 1TB Owning Table Product Product Product Product Product Product Product Product Product Product Product Product Product

Chapter 1

Using Flexible Attributes

The flexible attributes model enables a more dynamic set of data to be accurately modelled. For example, if a new product is introduced, with an entirely new set of attributes, these can be defined without changing the existing database schema.

Using Flexible Attributes

The flexible attribute model should be used to capture disparate types of data about the same database entity (such as the part model example in Understanding Flexible Attributes on page 8). Where data is common to most or all types of an entity, it should be modelled as a static attribute. In particular, if data is to be queried on, it probably should be defined as a static attribute - it does not normally make sense to use a flexible attribute as a filter field on a search form.

Definition and Instantiation

In order to use flexible attributes, you first need to define them, then you instantiate them. The definition must encapsulate which object should have (or acquire) the attributes, while the instance records an actual value of the attribute, associated with a single owning instance. For example, we may want to define that parts in the "Phone" family have a "Headset Color" attribute. Then, if we install a phone, the instance of the phone may have a value of "Red" for the "Headset Color" attribute.

Flexible Attribute Templates

If data is common to most or all types of an entity, it should be modelled as a static attribute. Therefore, flexible attributes are reserved for cases in which the flexible attribute data is common to only a select group of object entries. Templates are used to determine which flexible attributes are appropriate for a particular instance of an object. A template provides a logical grouping of flexible attributes definitions along with a set of conditions. If the template's conditions are met then all flexible attributes belonging to that template are valid for that object instance. Thus, flexible attributes must belong to a template in order to ever be instantiated.

Flexible Attributes Overview

Understanding Flexible Attributes Architecture

Understanding Flexible Attributes Architecture

The following sections briefly discuss flexible attributes implementation in different areas of the ClarifyCRM infrastructure, including the database, ClarifyCRM Business Objects, and the ClarifyCRM LAN infrastructure:

Understanding the Flexible Attributes Data Model on page 10 Accessing Flexible Attributes Using ClarifyCRM Business Objects on page 11 Accessing Flexible Attributes Using ClearBasic on page 11

Understanding the Flexible Attributes Data Model

To implement flexible attributes in the ClarifyCRM database, the following tables are used:

Base Table. A base table is an existing table that is identified as being able to use flexible
attributes by the inclusion of the line ALLOW_FLEX in the database schema.

Flexible Attributes Table. This is the table that holds the flexible attribute data. It is created by
the application only if ALLOW_FLEX is set in its related base table.

Flexible Attributes Definition Table. This table holds a definition for a set of attributes. Flexible Attributes Template Table. This table holds templates that include conditions to be
applied to the definitions for a set of attributes. Figure 1 illustrates the tables and relations in the database that are used to implement flexible attributes:
Figure 1 Diagram of Flexible Attributes Tables and Relations

Flexible Attributes Template Table (table_flex_tmpl)

Flexible Attributes Definitions Table (table_flex_defn)

Base Table (ALLOW_FLEX)

Flexible Attributes Table (table_fa_<basename>)

As illustrated in Figure 1, each base table with the ALLOW_FLEX designation in the database schema has an associated flexible attributes table that stores the instances of a defined attribute. The flexible attributes definition table stores the definitions for those instances. Finally, each of the definitions is related to one or more templates in the flexible attributes template table. Templates serve to apply conditions to flexible attributes.

10

Chapter 1

Understanding Flexible Attributes Architecture

A row in a base table can have zero or more related rows in its related flexible attributes table (named table_fa_<basename>). For example, if the base table is the Case table (table_case), then the flexible attributes table that the system creates for table_case is named table_fa_case. One or more rows in table_fa_case are related to one row in the flexible attributes definition table (table_flex_defn). That one row defines all of the related instances of the Case flexible attributes. Each of the flexible attributes definition rows can be related to one or more templates in the table_flex_tmpl table. For the Case table, you might have a template whose condition states that only cases from a particular area should be retrieved. For detailed information on the data model implemented for flexible attributes, see Appendix A, Flexible Attributes Data Model Reference.

Accessing Flexible Attributes Using ClarifyCRM Business Objects

To enable inserts, updates, and deletes to flexible attributes data to be accomplished in a similar way to static attributes data, business objects provide methods to access flexible attributes. The following changes are implemented in the baseBo object:

A new method is added: getFlexFields() The existing Query() method is modified to clear all of a business objects cached flexible
attributes data. Since the BO will have no cached FA information a subsequent call to getFlexFields() will perform a round trip and will retrieve the latest flexible attributes data. This feature is useful in cases where flexible attributes data for which templates are active may have changed. For more information on using ClarifyCRM business object methods to access flexible attributes, see Core Business Objects Reference Guide and Business Objects Programmers Guide.

Accessing Flexible Attributes Using ClearBasic

In the LAN client infrastructure, you can access flexible attributes programmatically through get and set methods implemented in ClearBasic. For more information, see the LAN client documentation, including ClearBasic Programmers Guide, API Toolkit Reference, ClearBasic Customization Guide, and ClearBasic Object Reference.

Flexible Attributes Overview

11

Understanding Flexible Attributes Architecture

12

Chapter 1

Appendix A

Flexible Attributes Data Model Reference

In This Appendix Flexible Attributes Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

13

Flexible Attributes Data Model

Flexible Attributes Data Model

For details on the tables in the ClarifyCRM data model used to implement flexible attributes, see the following sections:

Flexible Attributes Tables on page 14 Flexible Attributes Metadata Tables on page 14

Flexible Attributes Tables

Instances of flexible attributes data are stored in object specific tables with table names of the format: table_fa_<object_name>. Thus case objects store their flexible attributes data in table_fa_case. These flexible attributes data tables will only be created if the base object is marked ALLOW_FLEX in the schema. Table 3 describes the schema for each flexible attributes data table:
Table 3 Flexible Attribute Table Schema Column objid dev Data Type Number Number Usage Unique Identifier Traveler Support (this column only exists if Traveler is

enabled) attribute_name attribute_datatype attribute_value s_attribute_value String Number String String The attribute's name. This is a copy of the name given in the flexible attributes definition table. Represents the ClarifyCRM data type of the flexible attributes. String representation of the attribute's value. Searchable attribute_value. Only filled in when the flexible attributes is searchable.

NOTE: The attribute_name column is a copy of the flexible attributes's attribute_name as specified in the

flexible attributes definition table (see Flexible Attributes Definition Table on page 14). The flexible attributes infrastructure fills in the attribute_name field when writing the flexible attributes instance to the flexible attributes table (table_fa_<basename>). The attribute_name data is provided for application code usage and is not used or needed by flexible attributes infrastructure.

Flexible Attributes Metadata Tables

Flexible attributes use two metadata tables to support them:

Flexible Attributes Definition Table on page 14 Flexible Attributes Template Table on page 16

Flexible Attributes Definition Table

The table table_flex_defn contains the basic flexible attributes definitions. Every defined flexible attribute must have an entry in this table.

14

Flexible Attributes Data Model Reference

Flexible Attributes Data Model

Table 3 describes the schema for the flexible attributes definition table (table_flex_defn):
Table 4 Flexible Attribute Definitions Table Schema Column objid dev Data Type Number Number Usage Unique Identifier Traveller Support (this column only exists if traveller

is enabled) attribute_name attribute_datatype default_value description valid_values is_required String Number String String String Boolean The attribute's name. This is a copy of the name given in TFD (mentioned later). Represents the ClarifyCRM data type of the flexible attributes. String representation of the attribute's default value. User supplied description of the flexible attributes. String that holds the valid values for this attribute. Specifies if this is a required flexible attributes. (this flag is provided for the UI and is not used or enforced by infrastructure.) Initial date at which this definition becomes usable. If not set, there's no start date - attribute is active unless we passed an end date. Final date at which this definition ceases to be usable. If not set, attribute stays active forever. Displayable label or name for use by this attribute. Necessary because 'Name' must be unique across all definitions, so names like 'color3' may show up, whereas label does not need to be unique. Bitmask for holding internally defined application specific flags for this definition. Infrastructure will not look at or modify these flags under any circumstances.

effective_start_date

Date

effective_end_date Label

Date String

Flags

Number

What is stored in valid_values depends on the data type of the attribute (specified in the attribute_datatype field). For String fields, valid_values holds the name of a choice list (an hgbst_lst) which holds all of the valid strings for this definition. For Date types, valid_values holds a string that specifies a start and end date range in the format: ISO_DATE,ISO_DATE (for example: 11-23-2001 22:12:23, 03-03-2002 12:02:23). Finally, for numeric data types we support multiple ranges which should be specified in the form: start-end,start-end,start (for example: 3-4, 12-14). The valid_values field is for client-side (GUI) validation only. They will not be honored by infrastructure. The attribute_datatype holds the numeric data type of the attribute - as specified for regular fields in schema. Flexible attributes will support data types of String, Long, Float, and DateTime. No other data types are currently supported. The effective_start_date and effective_end_date fields are used to specify a date range over which this definition may be used. Either can be null, and this simply means there is no start or end date. For instance, an element with both start and end dates set to null will never go inactive as a result of effective dates.

Flexible Attributes Data Model Reference

15

Flexible Attributes Data Model

Flexible Attributes Template Table

The table table_flex_tmpl defines the flexible attributes templates. Table 5 describes the schema for the table_flex_tmpl table:
Table 5 Flexible Attribute Template Table Schema Column objid dev Data Type Number Number Number String Number Usage Unique Identifier Traveller Support (this column only exists if traveller is

enabled) type_id tmpl_name tmpl_type The object type for which the template applies User supplied name of the template. The template type can be set to the following values: 0 = the condition field specifies a condition. 1 = the condition field specifies a direct relation and this template is an origin template. 2 = this is a destination template for a direct relation and the condition field will be ignored. (For information on origin templates and direct relations, see Direct Relations on page 16) description condition
String String

User supplied description of the template. The condition which determines if this template is active. No condition means that the template is always active. Conditions follow the syntax: RelationPath:Field <operator> <value>. For example: "case2site;site2addr:state = 'CA'"

Direct Relations
Basic templates are described in Table 5. They have conditions which are validated in order to determine whether the attribute definitions associated with them are enabled or not. There are two additional types of templates that are used together to activate definitions. They are called Origin Templates and Destination Templates. Together they make up a scheme called Direct Relations. For performance reasons, direct relations can be used instead of conditions. A direct relation is a ClarifyCRM path between the focus object and table_flex_tmpl. The tmpl_type field in table_flex_tmpl determines whether a template is a basic template with a condition, a direct relations origin template, or a direct relations destination template. Origin templates hold a path statement in their condition field instead of a condition. This path statement must end at table_flex_tmpl. The customizer is responsible for adding the relation in the database to table_flex_tmpl. For example, here is a direct relation example path from table_case: case2site;site2flex_tmpl. When evaluating the origin template, the path is followed back to table_flex_tmpl. Any templates at the end of the path should be marked as destination templates. These destination templates are automatically activated (their conditions are not evaluated, and in fact should be left empty). Thus, the set of active templates is all those basic templates whose conditions are true, and all destination templates that are the targets of origin templates. Origin templates do not relate directly to attribute definitions, and thus do not activate them directly. They work only through destination templates.

16

Flexible Attributes Data Model Reference

Flexible Attributes Data Model

Direct relations notes: Origin templates are used to specify valid templates and may not directly specify flexible attributes. For example, origin templates should not be related to table_flex_defn. The conditions field of destination templates will be ignored. An object may have multiple origination templates each of which may evaluate to multiple destination templates. In general, the relation path between the focus object and table_flex_tmpl will be an origination template in which case there will be only one destination template per origination template. Templates not marked as destination templates should not be related to objects through direct relations.

Flexible Attributes Data Model Reference

17

Flexible Attributes Data Model

18

Flexible Attributes Data Model Reference