About Content ...................................................................................................................................... 12 BroadVision Database Concepts .......................................................................................................... 13 Content Tools and Utilities .................................................................................................................. 14 About the API ...................................................................................................................................... 15 Working with Content .......................................................................................................................... 16
Data ...................................................................................................................................................... 36 Types of Data ................................................................................................................................ 36 Types of Tables ............................................................................................................................. 37 Application Data Tables ........................................................................................................ 37 3
Co nte nts
Internal Tables ....................................................................................................................... 37 Metadata Tables .................................................................................................................... 38 Mapping Tables ..................................................................................................................... 38 Services ........................................................................................................................................ 38 External Data Sources .......................................................................................................................... 39 When to Use an External Source Data ......................................................................................... 40 Defining an External Data Source ................................................................................................ 41 User Profile Tables and LDAP ..................................................................................................... 41 Data Caching ........................................................................................................................................ 42
Basic Content Examples ...................................................................................................................... 68 Create New Content ..................................................................................................................... 69 Delete Content .............................................................................................................................. 70 Retrieve Content Using ContentUID .......................................................................................... 71 BroadVision, Inc.
Co ntents
Retrieve Content Using ContentKey as the Key .......................................................................... 72 Working with Multivalue Tables .......................................................................................................... 73 Create a Multivalue Table ............................................................................................................ 74 Insert Row in a Content Multivalue Table ................................................................................... 75 Delete Row in a Content Multivalue Table .................................................................................. 76 Update a Content Multivalue Table .............................................................................................. 77 Save a Content Item’s Multivalue Data ........................................................................................ 78 Setting Attributes and Rows ................................................................................................................ 79 Set an Attribute Value Within Content Using setValue() ............................................................. 80 Set an Attribute Value Within Content Using update() ................................................................ 81 Set Parent Row for Content .......................................................................................................... 82 Update Main Row of Content, Queue Series of Content List Update Records, and Perform Updates Concurrently .......................................................................................................................... 83 Working with Categories ..................................................................................................................... 87 Retrieve a Category ...................................................................................................................... 88 Create New Category ................................................................................................................... 89 Retrieve List of Content within a Category Matching a Given Set of Conditions ....................... 90 Add Members to a Category ........................................................................................................ 91 Create Child Category .................................................................................................................. 92
A
Working with Content Types and Schema Files
B
bv-updater
C
Glossary
133
Index
137
93
Configuring Content Types .................................................................................................................. 94 Extending Content Types and Profile Tables ....................................................................................... 95 About Content Types and Profile Tables ...................................................................................... 95 Adding a New Content Type ........................................................................................................ 96 Making New Content Types Searchable ............................................................................. 100 Adding Attributes to an Existing Content Type ......................................................................... 101 Modifying the Database Schema ................................................................................................ 103 Schema XML Files ............................................................................................................. 103 SchemaGenerator Utility ..................................................................................................... 106 Displaying New Profile Attributes ............................................................................................. 107 Replacing a Content or Profile Table ......................................................................................... 109 Configuring the Display Title for Content Items ............................................................................... 110 Configuring Content for Browsing .................................................................................................... 111
113
Configuration File for bv-updater ...................................................................................................... 114 Dependencies of bv-updater .............................................................................................................. 115 A Running BroadVision System ................................................................................................ 115 Environment Settings in the Operating System ......................................................................... 115 File Locations of the DTDs ........................................................................................................ 116 Input File Formats for bv-updater ...................................................................................................... 117 Content Input Files ..................................................................................................................... 117 Category Input Files ................................................................................................................... 123
5
Co nte nts
6
BroadVision, Inc.
About this Book
This guide describes content and how to work with it using BroadVision® tools and Content-related APIs. NOTE: This book does not discuss versioned content. BroadVision’s Content Services™ product
provides advanced content capabilities for your BroadVision system, including versioning. For information about versioned content, refer to the Content Services Guide.
Audience The Content Guide provides information for Portal™ developers new to BroadVision products. It contains detail about using, obtaining, and managing content in a BroadVision-based web application. Developers should be fluent in SQL, XML, Java, and database concepts. It is assumed the reader has read or has access to one or more of the following books: the Portal Developer Guide, Portal Administrator Guide, and Process Services Developer Guide.
Organization This book is organized as follows: • Chapter 1, “Introduction,” gives an overview of the major topics found within this book. • Chapter 2, “Content,” explains what content is, describes the different types of content, and introduces the terms associated with content. • Chapter 3, “Working with the Database,” offers a high-level description of database concepts as they pertain the content in a BroadVision framework, describes the kind of data found in a BroadVision database, discusses tables and the use of external sources when working with content. • Chapter 4, “Tools and Utilities for Working with Content,” describes the content management, loading, and other tools available to use when working with content. • Chapter 5, “Using the API,” gives a high-level overview of the Data Access API, its packages, and the classes with which you should become familiar. • Chapter 6, “Examples,” contains code examples using the Data Access API for retrieving and working with content and categories. • The appendices contain a glossary, details about configuring content types, extending content types, and using the bv-updater utility. Content Guide
7
About this Book T y pogra phica l C onven ti ons
Typographical Conventions This manual incorporates these typographical conventions. Fonts
• Sample code, commands, filenames, and directory names, are shown in monospace font: setup.bin • Significant items in code listings are shown in bold monospace font: visitor = Session.visitorManager.visitor(username); • Variables for which you must provide information are shown in italic monospace font: % setenv BV_DB_DATABASE DBNAME
• New terms and important words are shown in italics. • User interface menu items, buttons, and links that you are instructed to click are shown in bold. Special notes
NOTE: This lead-in calls out helpful information that is related to but distinct from the main topic. TIP: This lead-in indicates additional details, alternative methods, hints, shortcuts, and related
information about the main topic. IMPORTANT: This lead-in indicates situations that can prevent the system from running and how to
avoid them. File paths and environment variables
• By default, file paths are shown in Unix format. For example: directory/file_name
The equivalent on Windows would be: directory\file_name
• When commands differ depending on whether you are using Unix or Windows, both commands are shown. However, if the only difference between running the command on Unix or Windows is a file extension, the ext meta variable is used. Specify the extension appropriate for your environment. • Within text and file paths, install_dir represents the value specified for the installation folder when you installed the BroadVision software. This value can be replaced with the full installation path or, if you have set your BroadVision environment, the $BV1TO1 environment variable (%BV1TO1% on Windows). • Within text and file paths, config_dir represents the value specified for the configuration folder when you installed the BroadVision software. This value can be replaced with the full configuration path or, if you have set your BroadVision environment, the $BV1TO1_VAR environment variable (%BV1TO1_VAR% on Windows).
8
BroadVision, Inc.
About th is Bo ok Typ ograp hical Co nventio ns
• The entity relationship diagrams in this book use the following notations: one to one optional link one to many
Table in the subsystem
required link many to many
Content Guide
Table in another subsystem
9
About this Book T y pogra phica l C onven ti ons
10
BroadVision, Inc.
1
Introduction
The success of your website depends in part on how you organize and present your content. Before you create or modify a web application, it is important to understand how content is organized within the BroadVision framework. This chapter offers a high-level overview of content organization and the ways in which you can work with content and the BroadVision Data Access API. This chapter contains the following topics: • “About Content,” next • “BroadVision Database Concepts” on page 13 • “Content Tools and Utilities” on page 14 • “About the API” on page 15 • “Working with Content” on page 16
Content Guide
11
Ch apter 1 In trod uction Abo ut Co ntent
About Content Content consists of information that you organize and display in your website, whether the site’s purpose is to deliver employee announcements, sell products, or provide customer service assistance. In a BroadVision environment, an individual piece of content is referred to as a content item. Multiple pieces of information comprise a content item, which is contained in a database table row. For example, a content item can consist of a cell phone with an ID of “8267,” a product ID of “cell7418,” a store ID of “91,” and name of “7418 Cell Phone.” Database columns (also called attributes) hold the content item’s multiple pieces of information individually. The cell phone’s attributes are OID, PROD_ID, STORE_ID, and NAME. Content items are grouped into tables by content type. Within a content type, every content item has the same attributes, so the table that contains the 7418 Cell Phone has other content items with attributes of OID, PROD_ID, STORE_ID, and NAME. Content items can be arbitrarily assigned to categories within the content type. For example, the 7418 Cell Phone is included in a category named “Cellular.” Additionally, external content, which is any content that resides outside of a BroadVision database, can partially or completely comprise content items. The following diagram depicts the relationships between the various entities that make up BroadVision content.
Columns, or Attributes, are Different for Each Content Type
For additional information, refer to Chapter 2, “Content.”
12
BroadVision, Inc.
Chap te r 1 Introductio n Broad Vision Da ta base Con cepts
BroadVision Database Concepts BroadVision stores data in a relational database. Various types of data and tables comprise the database. For example, your application may use content data types, microsite data types, and more. Additionally, you can extend these data types. The types of tables that your BroadVision database contains include application data tables, internal tables, metadata tables, and mapping tables. Your application uses the application data tables, while internal tables are reserved for use by the BroadVision framework. Metadata tables are tables that describe the database. Finally, mapping tables are used with external content, which is content that resides in a database that is external to a BroadVision database. The database containing your tables may be partitioned into services. A service is a portion of your database dedicated to a particular purpose. For example, the Portal foundation application uses a service called “C3” for its sample data. You may find that you have a large amount of data in existence in an external data source. An external data source contains external content. You can use external content with a BroadVision database by utilizing the mapping tables. Refer to Chapter 3, “Working with the Database” for details about working with content data and the database.
Content Guide
13
Ch apter 1 In trod uction Co nte nt Tool s a nd Utilities
Content Tools and Utilities Content resides in and is accessed through a relational database. The content is loaded into the database primarily through the bvtool bv-updater, load-portal-data, and BroadVision Management Center tools. Database utilities such as bvtool bv-updater allow bulk loading of content
HTTP server Web browser
Application Server: BVMC, Inline Publishing
Allows creating and editing of individual content items, creating and manipulating of categories, business rules, and more.
database
Allows creating and editing of individual content items.
You use these tools to control information in your web application and determine what content gets displayed to which visitors. For example, an administrator can use the BroadVision Management Center to categorize content or make it available for viewing on a website. See Chapter 4, “Tools and Utilities for Working with Content” to read more about using the BroadVision Management Center, bvtool bv-updater, load-portal-data and other tools. In particular, make sure to understand the functionality of content and categories in the BroadVision Management Center. See the Portal Administrator Guide for additional information about using the BroadVision Management Center.
14
BroadVision, Inc.
Chap te r 1
Introductio n About the API
About the API You can use the BroadVision Data Access APIs to retrieve content and display it on your website using Java. For example, perhaps you would like your users to be able to retrieve a list of all content within a category named “equipment” when they perform a search within a particular page of your site. You can create this functionality using the classes and methods available within the API. To learn about the Data Access API and to see examples, refer to Chapter 5, “Using the API,” and Chapter 6, “Examples.”
Content Guide
15
Ch apter 1 In trod uction Working with Con te nt
Working with Content Once content has been entered into the database and made available to your web application, you can use various mechanisms to retrieve it. For example, you can use: • Queries to access the database directly. See the BroadVision Javadoc for information about methods that support database queries. Additionally, see Chapter 5, “Using the API” and Chapter 6, “Examples.” • Search adaptors to provide the integrations connecting BroadVision Portal and Process with third-party, full-text search solutions. See the BroadVision Search Adaptors Guide for more information. • Rule sets to generate content to display in programs. The content a rule set generates is based on the rules that comprise the rule set. See the Portal Administrator Guide for details about implementing rules. • Segments to let you personalize site content and email communication with site visitors. Use segments to define a target audience of visitors with similar characteristics. See the Portal Administrator Guide to learn more. • Category roles to let you control access to content categories and content items. See the Portal Administrator Guide to learn more. • Content categories to help organize large amounts of content for access by browsing. They also help segregate content into separate areas of responsibility and control. See the Portal Administrator Guide to learn more.
16
BroadVision, Inc.
2
Content
Content consists of data that is structured so you can present it in a way that makes sense to your users. This chapter describes what content items are, how they pertain to content types and categories, and how you can extend the content schema. This chapter contains the following topics: • “Content Items,” next • “Attributes” on page 18 • “Content Types” on page 21 • “Content Identifiers” on page 25 • “Categories” on page 27 • “External Content” on page 33 • “Extending the Content Schema” on page 33
Content Guide
17
Ch apter 2 Conten t C o n te n t I t e m s
Content Items In the simplest case, a content item is composed of the information contained in all the fields in a single row in a database table. The following example shows some of the fields of a content item from the BV_PRODUCT table.
Individual fields in the row hold information specific to the content item Information in a single row constitutes one content item
OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
Content items are logically grouped into tables by content type. Content types have columns or attributes that contain descriptive information.
Attributes The columns of a table are referred to as attributes. This is because when a web application retrieves a content item from the database, it acquires a content object that is modeled after the database. The attributes of the object correspond directly to the columns in the table. (See Chapter 5, “Using the API,” for more information.) The attributes of a content item contain information such as IDs, names, and descriptions that serve to describe the content item and to distinguish it from other content items in the same table. Some of the attributes contain information that can be displayed on the visitor’s browser and some attributes contain information that is used by various elements of the application system. For example, the following diagram shows a portion of the data row for one content item, the Next Gen DSL Modem. The attributes are in uppercase.
Columns or Attributes
Content Item
18
OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
BroadVision, Inc.
Chap te r 2
Co ntent Attrib utes
CREATION_TIME is a required content type attribute. (See “Required Attributes for Content Types” on page 24.”) Other content attributes provide necessary information about content that is not normally displayed to a visitor, such as the location of an image file and its dimensions. Your application would typically use the location and measurements of an image file to retrieve the image and to determine its size when displaying it on your site. NOTE: The path to an image file is stored in the database, while the image file itself is stored
externally. Storing images outside the database reduces the database memory footprint.
Multivalue Attributes Attributes generally describe a single characteristic about a content item, such as name or color. However, some attributes contain a list of values, such as a list of a product’s available colors. In BroadVision, such multivalue attributes are represented as the child tables in one-to-many relationships, where the content table is the parent. IMPORTANT: Multivalue attributes are also referred to as related attributes, related attribute lists, or list tables in other BroadVision documentation.
Multivalue attributes behave the same as ordinary single value attributes in that you can search through them and include them in queries. For example, if you wanted to add a child table to BV_PRODUCTS named MODEM_MANUFACTURER that contains the name of all modem manufacturers that you stock, you could then perform a search for modems and the manufacturer name to find all modems by that company.
BV_PRODUCT
MODEM_MANUFACTURER Related by OID
OID
PROD_ID
STORE_ID
NAME
8266
123modem
91
Next Gen DSL Modem
CREATION_TIME
OID
BUNDLE_ITEM
2008-01-17 11:53:44.90000000
8266 8266
GREEN ACME
Tables can have more than one multivalue attribute. You could have separate multivalue attributes for accessories and manufacturers. With this arrangement, searching for modems made by ACME that come with splitters returns a modem whose OID is 8266.
BV_PRODUCT
ACCESSORY
MODEM_MANUFACTURER Related by OID
Related by OID OID
ACCES
8266 ETHERNET 8266 SPLITTER USB 8111
OID
PROD_ID
STORE_ID
NAME
8266
123modem
91
Next Gen DSL Modem
CREATION_TIME 2008-01-17 11:53:44.90000000
OID
BUNDLE_ITEM
8266 8266
GREEN MODEM ACME
Getting a row of information out of a multivalue table retrieves a multivalue row. For example, when searching for USB modems made by ACME, the multivalue rows retrieved would be those containing USB, Next Gen DSL Modem, and ACME. Content Guide
19
Ch apter 2 Attrib utes
Conten t
Containment Relationships Entries in a multivalue attribute table rely on the parent object. In the example earlier, COLOR is only meaningful in relation to a related product. COLOR cannot stand on its own and is therefore an appropriate multivalue attribute. On the other hand, if a list represents information that can exist on its own, make it a separate content type instead. For example, the following list of computer printer supplies in COMPUTER_ACCESSORIES is a separate content type, not a multivalue attribute.
BV_PRODUCT
related by OID
MultiValue Table
related by OID
COMPUTER_ACCESSORIES
OID
NAME
OID
OID
OID
ACCESSORY_I
NAME
6777
Inkjet Printer
6777 6777 6777
8100
8100
43
26 lb. paper
PRICE 6.99
8101 8102
8101
109
10' exten.
21.99
8102
585
Stand. Ink Cart.
42.50
6777
8103
8103
1004
Delux Ink Cart.
78.99
For information about: • Referencing multivalue attributes in applications or components, see “TableData” on page 59 as well as the Javadoc. • Referencing multivalue attributes in database activities at the server level, see “Content” on page 57 and refer to getListData(), which returns the content’s multivalue table entries based on list name. Also see the Javadoc. • Creating conditions using multivalue attributes, see the Portal Administrator Guide. Note that in that publication, multivalue attributes are sometimes referred to as related attributes.
20
BroadVision, Inc.
Chap te r 2 Co ntent Conten t Typ es
Content Types A content type acts as a template for content items. A content type defines the columns in a table, referred to as attributes, and defines what kind of data each attribute can hold. For example, the BV_PRODUCT table contains Portal product information.
Portion of BV_PRODUCTS OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
8267
cell7418
91
7418 Cell Phone
2008-01-17 11:53:44.90000000
BroadVision provides several content types that you can use and extend for your own applications. The content types can be used as-is, or they can form the basis for any custom content types you want to create. Each content type resides in its own content table. The following table describes some of the content types that are installed when you purchase Portal.
Content Type
Description
Content Table
Advertisements
Ads displayed on your site to promote the products and services sold by your company or your customers’ companies.
BV_ADVERTISEMENT
Discussion Forum Groups
On-line interactive forums that foster BV_DF_GRP a sense of community among your site visitors and are accessible from your site. Discussion Forum Groups uses a different user interface, not the BroadVision Management Center, and a different API than content types.
Content Guide
Editorials
Text and media presentations, such BV_EDITORIAL as investment reports and articles, that are displayed on your site to distribute knowledge for intranets, the internet, and extranets.
Portal URLs
The BV_URL table handles the URL BV_URL content type.
Products
Items and services offered for sale to BV_PRODUCT business or retail customers on electronic commerce sites.
21
Ch apter 2 Conten t Co nte nt T ypes
Here you can see content types displayed in the BroadVision Management Center.
22
BroadVision, Inc.
Chap te r 2 Co ntent Conten t Typ es
Schema Specification Files Schema specification files define content types. Each schema specification file contains a set of keyword statements that specify the content type, the table name, the column names, the data types that the columns can hold, and a number of other characteristics. The Portal schema specification files (*_spec.xml) for the database are found in install_dir/setup/install/srcxml.locale. Some of the most common schema XML files you might want to modify include: • prod_spec.xml – Products content type • edit_spec.xml – Editorials content type • adv_spec.xml – Advertisements content type • prof_spec.xml – User profile tables For example, these elements from prod_spec.xml define the Products content type’s Product ID attribute.
Element
Description
Example
ATTRIBUTE
Refers to a specific column
NAME
The attribute (column) name
PROD_ID
TYPE
The attribute’s (column’s) data type.
STRING
NOT_NULL
Optional to indicate that a column’s value cannot be null.
ATTR_KIND
Specifies the following optional properties of the attribute: Indicates that the attribute is part of a primary key or unique index.
COLUMN
A custom value for the column type.
varchar(80)
FRIENDLY_NAME
The attribute’s friendly name.
Product ID
SEMANTICS
A description of the attribute.
Product ID
Portion of BV_PRODUCTS
Content Guide
OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
8267
cell7418
91
7418 Cell Phone
2008-01-17 11:53:44.90000000
23
Ch apter 2 Conten t Co nte nt T ypes
Required Attributes for Content Types All content types have six required attributes that are integral to the operation of a BroadVision application. These attributes cannot be left null.
Attribute
Comments
The name of this attribute varies by content type. It must be the first attribute defined for the content type. Its value must be unique for each content item. See “Content Key” on page 25 for more information.
STORE_ID
The website service that provides this type of content.
CREATION_TIME
The time the content item was created in the database. Automatically entered by the BroadVision Management Center.
STATUS
Whether the content item is available for display and operations. This attribute’s value is either On-line or Off-line.
DELETED
Indicates whether or not the content item has been deleted from the database. This attribute exists for compatibility reasons with 7.1
LAST_MOD_TIME
The last time the content item was modified. Automatically modified by the BroadVision Management Center.
For example, notice that BV_PRODUCT has a PROD_ID attribute, which is the content key. Additionally, if you look at the table in the database, you can see that it contains the five other required attributes.
Required Attributes
OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
STATUS
DELETED
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
91
0
LAST_MOD_TIME 2008-01-17 11:53:44.90000000
8267
cell7418
91
7418 Cell Phone
2008-01-17 11:53:44.90000000
91
0
2008-01-17 11:53:44.90000000
NOTE: Content types may have additional required attributes that may or may not be required or
even exist for other content types. For example, the Products content type has a required attribute called PRICE which is not defined for either the Editorials or the Discussion Forum Groups content types. You can add whatever data types, content types, or attributes you want.
24
BroadVision, Inc.
Chap te r 2 Co ntent Co ntent Ide ntifi ers
Content Identifiers Queries cannot produce reliable results unless content items in the database are uniquely identifiable. Several attributes exist to ensure that each content item remains distinguishable from other content.
Content Key The content key is an attribute that uniquely identifies a content item. The name of the content key varies from content type to content type. For example, the content key for the Products content type is PROD_ID while the content key for Editorials is ED_NAME. It usually consists of a string column of varchar() type, although it can also be an INTEGER. For a content key of type STRING, the value given with the varchar() specification varies with the expected needs of the particular key. For example, the value for Discussion Forum Groups is varchar(220) but for Products it is varchar(80). The content key can also consist of multiple attributes called a compound key. Any combination of attributes from within the table can comprise these attributes. You may find that you must retrieve content using a content key because you do not know a content item’s OID. See “Retrieve Content Using ContentKey as the Key” on page 72.
OID Besides the content key, all content items have another unique identifier that the BroadVision framework automatically assigns called the OID (or object ID). The BroadVision framework uses the OID to relate various tables together. For example, content items are related to categories by OID through an internal table (see “Categories and the Database” on page 28). BroadVision tools such as the BroadVision Management Center and the bulk load utilities automatically assign a unique OID to each new content item for that content type. The APIs for inserting content also automatically assign a unique OID to each new content item for that content type. The internal routines that support these tools and APIs buffer sets of unassigned OIDs and assign them to new content items as they are created, ensuring the referential integrity of the data tables. For example, if want to retrieve all content that has to do with cellular phones from a single content type—for instance, Products—you can use OID. NOTE: Always use the BroadVision tools or APIs to assign OIDs or referential integrity may be lost.
Content Guide
25
Ch apter 2 Conten t Content I denti fi e rs
Content UID In addition to the Content Key and OID, every content item in the database has a unique content UID, which consists of three fields—the content type ID, service ID, and OID. The content UID exists because the OID is not necessarily a unique value within the database. An OID is unique in its content type. You can use the content UID to retrieve a content item using the API if you know all three fields that compose the content UID. See “Retrieve Content Using ContentUID ” on page 71.
GUID GUID refers to Globally Unique Identifier. OIDs are unique in their content types, while GUIDs are unique across all content types. For example, if want to retrieve all information that has to do with cellular phones from both the Products content type and Advertisements content type, you would use the GUID.
26
BroadVision, Inc.
Chap te r 2 Co ntent Categori es
Categories Categories hold references to arbitrary groups of content items that you create for a content type. Properly organized and implemented, categories can enhance the success of your website. Categories implement a hierarchical organization of content items within a content type that helps visitors find specific items. For example, if your website sells business products and services, the Products content type could contain product offerings such as wireless telephones, DSL services, and games. Having a separate category for each of these offerings makes it easier to present the right content for a particular visitor. You create categories and subcategories with either the BroadVision Management Center or the bulk-loading utility bv_updater. The BroadVision Management Center displays categories in a hierarchy that descends from the content type. NOTE: Even though the BroadVision Management Center displays categories in a hierarchy that descends from the content type, categories are not part of a content type.
The following screen shot from the BroadVision Management Center shows a Products subcategory named Cellular.
Content Type Subcategory
Both bv_updater and the BroadVision Management Center are discussed in Chapter 4, “Tools and Utilities for Working with Content.” For detailed information on creating categories in the BroadVision Management Center, refer to the Portal Administrator Guide.
Content Guide
27
Ch apter 2 Conten t Ca teg ories
Categories and the Database A single table named BV_CATEGORY contains the categories for all content types. The categories in BV_CATEGORY do not contain content items. Instead, a content item is related to the category name by OID (see “OID” on page 25). BroadVision maintains the mappings between categories and content items using the BV_CONTENT_REF table. BV_CONTENT_REF maps content item OIDs to category OIDs. Although the diagram below only shows the Products content table, the same relationship exists for each content table.
BV_CONTENT_REF BV_CATEGORY
related by OID
maps content to categories by OID
related by OID
BV_PRODUCT
Through this relationship, content items can be referenced through more than one category. For example, a cell phone could be referenced through two categories, Cellular and Mobile.
BV_CATEGORY
related by OID
BV_CONTENT_REF
NAME
OID
PARENT_OID
OID
Cellular
-8027
8267
Mobile
-8557
-8027 -8557
8267
related by OID
BV_PRODUCTS OID
PROD_ID
8267
cell7418
STORE_ID 91
NAME 7418 Cell Phone
CREATION_TIME 2008-01-17 11:53:44.90000000
NOTE: Category OIDs are negative while content OIDs are positive.
28
BroadVision, Inc.
Chap te r 2 Co ntent Categori es
Categories, Channels, and Programs BV_CATEGORY contains multivalue tables that define channels and programs for Portal. Channels organize areas of information into navigation hierarchies, and can be either topic-oriented or process-oriented. Channels within channels are sometimes called subchannels and have the same qualities as their parent channels. Programs are blocks of information carried by channels. When viewing a channel, you have choices of different programs or of different subchannels with programs of their own. Programs contain articles, documents, or other information. As you work with BroadVision products, you will become familiar with the concept of channels and programs. Notice that while a category/content relationship defines a content hierarchy, a channel/program relationship refers to a virtual hierarchy. The Portal-specific extensions to BV_CATEGORY for channels and qualifiers include: • BV_KM_CHANNEL • BV_KM_ORDER • BV_EP_CHAN_ORDER • BV_EP_QV_CHAN • BV_EP_CONTAINER • BV_EP_CAT_ORDER You can find a program’s parent channel by performing a search in BV_CONTENT_REF, the table that defines the relationship between channels and programs. For detailed information about the tables refer to the BroadVision Database Schema.
Content Guide
29
Ch apter 2 Conten t Ca teg ories
Uncategorized Content Content items do not need to belong to a category. When content items do not belong to a category, the content item is considered uncategorized. NOTE: When a content item is uncategorized it has no entry in the BV_CONTENT_REF table.
Every content type can have uncategorized content items. The BroadVision Management Center displays these items under the Uncategorized content tab.
Uncategorized content
Content items become uncategorized: • When you remove a content item from one category and do not put it into another one, and the item is not referenced by other categories. • When you delete a category, and the content items in it are not referenced through other categories. • When content items are bulk loaded with bv-updater and the category is not specified during the loading process. (For detailed information about bulk loading and classifying content items, refer to the Portal Administrator Guide.) You can move uncategorized content into a category in the hierarchy or you can delete it from the content database. See the Portal Administrator Guide for details.
30
BroadVision, Inc.
Chap te r 2 Co ntent Categori es
Caveats and Application Concepts for Categories Categories are contained within a single content type—they cannot span content types. All content items within a category have the same attributes. The same category name can exist for more than one content type, but the categories themselves are different—they reference different content types. For example, the C3 sample data contains the Products content type, which has an Equipment category defined. Equipment has a subcategory named Phones. Finally, Phones has a subcategory named Cellular, which lists cell7418 and cell 5562—cell phones from the BV_PRODUCT table. You can create a category named Cellular for the Advertisements content type, too. However, the content that the category for Advertisements accesses would come from the Advertisements content type table (BV_ADVERTISEMENT), not the Products content type table (BV_PRODUCT). The following screen shot of the BroadVision Management Center shows the results of a query. Two items—cell5562 and cell7418—are returned for the Products content type Cellular category. Only one item—Modern Cellphone—is returned for the Advertisements content type Cellular category.
Category: Cellular Content Type: Products
Content Items Returned
Category: Cellular Content Type: Advertisements
Content Item Returned
BroadVision recommends keeping your categories to a logical minimum. For example, you could create a separate category for each type of wireless telephone on your site, but using a simple query to retrieve all wireless telephones by a particular manufacturer from the database instead is more efficient. Content Guide
31
Ch apter 2 Conten t Ca teg ories
If you reference a parent category in your application, you reference all the content in all of its subcategories. The growth of BV_CONTENT_REF is not linear. It increases as a function of both the number of categories and the number of content items referenced through each category. If many items are referenced through multiple categories, it is possible for BV_CONTENT_REF to grow quickly. For example, three content items that are each referenced through three different categories will result in nine rows in BV_CONTENT_REF. If this table gets too large it can slow queries that are based on category.
32
BroadVision, Inc.
Chap te r 2 Co ntent External Co ntent
External Content Content is usually stored in the BroadVision content database. However you can store, retrieve, and update content stored in an external source provided if your site is configured to do so. Once you configure your source, content that is stored externally behaves the same as content from an internal source, but with these limitations: • You can have only one content table per content type, and there must be one unique key per row in the table. • You cannot mix internal and external content and multivalue attribute tables. You cannot link an external list table to an internal content table. • There is no guaranteed transactional integrity. If an external insert fails, the local insert fails too. • External data is always cached locally once fetched and is cached in content caches just like other content. • External data can be updated seamlessly from the BroadVision Management Center or Portal foundation application once you have defined your external data source. External data sources are described in “External Data Sources” on page 39.
Extending the Content Schema There are times when you may want to extend your content schema. For example, perhaps you would like to create a content type for announcements. You can do this by taking an existing schema file, copying it, and performing a few steps. Additionally, you can extend the schema for existing content types to add attributes to a main table, add attributes to a multivalue table, or add a multivalue table. See “Working with Content Types and Schema Files” in the appendices for stepby-step instructions.
Content Guide
33
Ch apter 2 Conten t Extendi ng the Conten t Schema
34
BroadVision, Inc.
3
Working with the Database
All information in the database can affect content retrieval and display. Understanding the issues and concepts related to content and the database helps you to more fully utilize the capabilities of BroadVision products. This chapter contains the following topics: • “Data,” next • “External Data Sources” on page 39 • “Data Caching” on page 42
Content Guide
35
Ch apter 3 Da ta
Workin g with th e D atabase
Data Content resides in a database, however, not all information in the database is content. Some of the information in the database only indirectly relates to content. For example, the BV_USER_PROFILE database table contains the visitor profiles, but these profiles become involved in content retrieval operations only if particular Portal features are enabled and utilized. Additionally, some of the database tables are used directly by your application, and some are used internally by the BroadVision framework. This section describes the different types of data and data tables that compose the database as well as external content sources. IMPORTANT: Never load data directly into the database with SQL statements or you may risk breaking referential integrity and corrupt the data.
Types of Data Extended data types (*_type.xml or *_types.xml) are based on your DBMS’s primitive data types. Extended data types are used by your schema specification files to indicate what type of data your content types will use. Extended data types are described in the schema specification files located in install_dir/setup/install/srcxml.locale. For example, if you open prod_spec.xml, you will see that it contains an element named TYPE_FILES that holds information about the extended content data type cnt_type.xml: cnt_type.xml
Extended data types for Portal, Custom extended data types for processes, and extended data types for Commerce Services™ exist: • Portal Extended Data Types – Added to the BV_TYPES table when Portal is installed and include Content (cnt_type.xml), Profile (prof_type.xml), Notification Scheduler (sched_type.xml), Portal (ep_non_extendable_types.xml), Collaboration Space and Microsite Data (cs_extendable_types.xml) • Custom Extended Data Types for Processes – Defined in ssp_type.xml • Commerce Services Extended Data Types – Added to the BV_TYPES table when you install Commerce Services and include Commerce Services (mr_data_types.xml, data_types.xml and also cnt_type.xml) IMPORTANT: You should generally only extend the following data types:
• Collaboration Space and Microsite (cs_extendable_types.xml) • Portal (ep_extendable_types.xml) To extend one of the above data types, add a new TYPE element to the *_type.xml or *_types.xml file. See the BroadVision Database Schema for information.
36
BroadVision, Inc.
C hapter 3
Wo rki ng with th e Databa se D at a
Types of Tables You use different types of tables with your application, depending on what task you perform, including application data tables and internal tables. Additionally, if you use an external data source, you use mapping tables.
Application Data Tables Application data tables are used directly by your application. The application actively retrieves or stores data in some of these tables. In other cases, your application specifies a named row of data, and internal systems do the rest. Examples of application data tables include: • The content and category data tables that you access when retrieving content items or categories of content items, such as BV_PRODUCT, BV_EDITORIAL, BV_ADVERTISEMENT, and BV_CATEGORY. • The visitor data tables that you access when validating or storing user logins, shipping addresses, visitor preferences, or other visitor related information such as BV_USER_PROFILE and others.
Internal Tables In contrast to application data tables, internal tables are used primarily by the BroadVision framework. Internal operations uses the information contained in these tables. Examples of internal data tables include: • The attribute and data type tables such as BV_ATTRIBUTES, BV_ATTRIBUTES_EXT, BV_ATTR_GROUP, BV_ATTR_GROUP_INFO, BV_DATE_TIME_VALUES, BV_DOUBLE_VALUES, and BV_ENUM_VALUES. For example, the BV_ATTRIBUTES table contains the columns for the database schema and associates it with a table name. It contains the details for the BV_PRODUCT table’s PROD_ID column as well as other columns. Portion of BV_ATTRIBUTES SCHEMA_NAME
ATTRIBUTE_ID
TABLE_NAME
ATTRIBUTE_NAME
TYPE_NAME
BV_PROD
1
BV_PRODUCT
PROD_ID
STRING
• Tables used to relate other tables together, such as BV_CONTENT_REF which relates categories and content items together. Refer to “Categories and the Database” on page 28. • Tables used to record transitional information as content is updated or manipulated in some way by an application such as the BroadVision Management Center: BV_CONTENT_LOG, BV_CATEGORY_PLUS, and others.
Content Guide
37
Ch apter 3 Da ta
Workin g with th e D atabase
Metadata Tables When a DataAccess API retrieves a content item from the database, it extracts the information contained in the desired row of a particular table and packages it as an object. To accomplish the mapping from database to object, BroadVision uses metadata tables that describe the database. Tables such as BV_CONTENT_MAP, which defines all content and content names, and BV_ATTRIBUTES, described in Internal Tables, are considered metadata tables. All meta tables definitions reside in install_dir/setup/install//meta_data.sql.
Mapping Tables The mapping table maps attributes to key columns in external tables. This table identifies the external table and the mapping table. See “External Data Sources” on page 39 for additional information. For a complete list and detailed descriptions of the tables, refer to the BroadVision Database Schema.
Services In addition to data types and tables, you can organize your content using a service. A service is a portion of the database devoted to a particular purpose. For example, the Portal foundation application uses data from the C3 service. You can use the BV_STORE table to find information about each service, including the service name. For example, in BV_PRODUCTS, a column named STORE_ID exists. This column identifies the Next Gen DSL Modem as having a service ID of 91.
BV_PRODUCT OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
If you look at BV_STORE, you can see that STORE_ID identifies the C3 service.
For information on adding a new service, see the BroadVision 8.2 Installation Guide. NOTE: Content items are not shared across services. If you log into the BroadVision Management
Center and select a service other than C3, you will not see the Next Gen DSL Modem as a content item because this product belongs with the C3 service.
38
BroadVision, Inc.
C hapter 3
Wo rki ng with th e Databa se External Da ta So urces
External Data Sources External source data is information stored in databases outside of BroadVision database tables that can be referenced from within BroadVision as if it were stored in a BroadVision table. To reference the data, the BroadVision framework maps content IDs to unique column names in the external system through mapping tables. The BV_EXT_MAP table identifies the mapping table between external tables and the BroadVision mapping table. The mapping table maps attributes to key columns in external tables. This table identifies the external table and the mapping table. In the example below, EXT_CONTENT_MAP is a mapping table. To request a product description, which is stored in an external table, you would ask for BV_PRODUCT.DESCRIPTION and the BroadVision framework would automatically retrieve the correct data based on the mapping. BV_PRODUCT
related by OID
EXT_CONTENT_MAP
EXT_PROD_CONTENT DESCRIPTION
22135
22135
Next Gen Modem
8267
22136
22136
Premium 7418 Phone
8268
22137
22137
Econ 5562 Cell Phone
8269
22138
22138
Standard Cable
CNT_ID
8266
8266
8267 8268 8269
...
related by CNT_ID
CNT_ID
OID
OID
Mapping tables contain key values for each external content record. NOTE: The mapping tables are a snapshot of the key mappings at the time that the table was last
populated or updated only. When external records are added, or when the keys change, you need to update the table by using the API. For example, you could use DataManager.createContent(...) to create entries in the BroadVision, mapping, and external tables. See “Create New Content” on page 69. A bulk loading tool such as bv-updater does not exist for external content. Your external database and the BroadVision runtime database can be different vendors. For example, you could use Oracle for your BroadVision runtime database and MySQL for the external database. In this case, the other vendor's JDBC JAR file(s) needs to be included in the classpath. If the database vendor type is not supported by BroadVision, a new Java class needs to be implemented based on the interface com.broadvision.data.server.DataAccessor. When you use external source data, keep the following points in mind: • You can have only one content table per Content Type, and there must be one unique key per row in the table. • You cannot mix internal and external content and multivalue attribute tables. You cannot link an external multivalue table to an internal content table. • There is no transactional integrity. • External data is always cached locally once fetched.
Content Guide
39
Ch apter 3 Workin g with th e D atabase Ext ernal Da ta Sou r ce s
• You may have external multivalue attributes, but you must also have an external “parent” table with the same key values as the multivalue table; the mapping table must be internal. BV_PRODUCT OID
...
related by OID
EXT_CONTENT_ related by CNT_ID OID CNT_I
EXT_PROD_CONTENT CNT_ID
DESCRIPTION
related by CNT_ID
UPGRADES_AVAIL CNT_ID
UPGRADE
Next Gen Modem
22136
2 Year Plan Loss Insurance
8266
8266
22135
22135
8267
8267
22136
22136
Premium 7418
22136
8268
8268
22137
22137
Econ 5562 Cell
22136
8269
8269
22138
22138
Standard Cable
22136
When to Use an External Source Data It is a good idea to use external data sources when: • You already have existing data elsewhere that was created and is being updated by a nonBroadVision application. • You already have a large amount of existing data that is too difficult to move into your BroadVision system. You can keep the data external, even though you intend to put it under the control of your BroadVision-based application. Accessing an external data source is slower than accessing a BroadVision database because there is additional lookup time required due to the mapping table. Additionally, there is access time incurred by communicating with the external database system. However, once data has been retrieved, if it is cached, there is no additional performance overhead. NOTE: For performance reasons, if you must use an external data source, make sure that you take
advantage of caching to minimize the effect of the additional lookup and retrieval time.
40
BroadVision, Inc.
C hapter 3
Wo rki ng with th e Databa se External Da ta So urces
Defining an External Data Source When using an external data source, you must create a connection pool based on your application server. To learn how to create a connection pool, see the Process Services Developer Guide. 1. Create a connection pool for the new data source and a data source that references the connection pool based on your application server. 2. If the data source needs a different JDBC driver, add the driver to the classpath in the application server’s startup script. 3. Add a new data source mapping. 4. Deploy the data source using the bvtool utility and restart the applications server.
User Profile Tables and LDAP User profile tables contain identity information about application users. For user profile tables, you integrate your BroadVision system with LDAP. The following list describes the four configuration files with which to become familiar for the external profile data source integration. • The external_profile_config.xml file is used by the user profile subsystem to access external LDAP profile attributes. • The group_config.xml file is used by the user profile subsystem to access user groups in external data sources. • The external_authentication_config.xml file is used by the user profile subsystem for external authentication. • The external_data_mapping.xml file specifies the mapping between the real name (the handle in BroadVision) and the actual name in the external data source. If you have multiple external data sources, you need to configure these files on all systems. After editing these files, you need to apply the configuration changes to your running system. See the BroadVision 8.2 Installation Guide for additional detail.
Content Guide
41
Ch apter 3 Workin g with th e D atabase Da ta Ca ch ing
Data Caching Caches are used to improve the performance of activities that access the database and where the result of queries can be reused for later evaluations. For example, rules may be used to find content while browsing through the site. In Portal, the following caches are also available in addition to content caches: • Text cache – stores text segments from pages • Filter cache – stores qualifier values for content items All BroadVision caches contain the most recently accessed items.
Application Server Cache BroadVision Management Center
Content and category data cached.
Database
When you restart the system, it reverts to the settings specified in the configuration file. Once you find the correct setting using the BroadVision Management Center, you can make the change permanent by changing the parameter in the configuration file. Increasing the size of the caches requires more memory. If you have issues with memory storage space, you can reduce the number of items stored in the text caches. You can manually flush the cache by using the BroadVision Management Center or by using bvtool. The bv_ptc_cfg.xml file located in the config_dir /appConfig/bv_framework/etc directory contains the definitions for text caches. Modify this file when you are satisfied with the cache flushing settings on your system. See the Portal Administrator Guide for more details. For information about working with data caches, see com.broadvision.data.cache in the Javadoc.
42
BroadVision, Inc.
4
Tools and Utilities for Working with Content
BroadVision provides multiple ways for you to load content into your database. Additionally, when you work with content, you will need to become familiar with various tools and utilities. This chapter contains the following topics: • “Content Management and Bulk Loading Tools,” next • “Other Tools” on page 49
Content Guide
43
Ch apter 4 Too ls and Utili ti es for Worki ng with Conten t Co nte nt Man age me nt an d Bulk Loa ding T ool s
Content Management and Bulk Loading Tools You can use different mechanism for loading content into the database depending on your situation and the role of the person loading content. Here are some of the tools you can use to manage content and load it into your database: • LoadUsers – used to import user information into your BroadVision visitor database if you use Portal or Process. • load-portal-data – used to import Portal-specific elements. • bvtool – multi-purpose utility to perform a variety of tasks, including importing, updating, and deleting content or category information into your BroadVision content database. • BroadVision Management Center – tool to enter and edit information in the database and also create a personalized experience for your site visitors. The BroadVision Management Center is bundled with Portal and allows you to establish logic to select the content you would like to display to visitors of your site. • Inline Publishing – users may publish content directly by using the Portal site if they have been given permission to do so.
LoadUsers The LoadUsers utility imports user information into your BroadVision visitor database. The utility processes data contained in an XML file. See the Portal Administrator Guide for more details.
load-portal-data The load-portal-data utility imports the following information into Portal:
• Channels
• Display Templates
• Programs
• Blocks
• Qualifiers
• Page Types
• User Templates
Use the utility to import and delete Portal information. For example, you might have a portal with a complex information architecture with lots of channels, programs, and types of users. You can manage the information architecture online through the BroadVision Management Center. However, for bulk operations, you may find it useful to maintain the definitions for your information architecture in separate input files to the load-portal-data utility, and run the utility after you make modifications. For additional details about using load-portal-data, see the Portal Administrator Guide.
44
BroadVision, Inc.
Chap te r 4
Tool s an d Uti lities fo r Working wi th Co ntent C ontent Ma nag ement a nd Bulk Lo adin g Too ls
bvtool The bvtool utility is a multi-purpose tool that allows you to better maintain and manage content in the database. For example, the bv-updater command allows you to load, update, and delete content and categories as well as perform other tasks, while the set-db command allows you to change the database settings for your BroadVision system. Additionally, you can deploy configuration changes, display and set parameter values, and deploy an application using bvtool. The following utilities are described in this section: • “bv-updater” on page 45 • “set-db” on page 45 • “bv-xmldumper” on page 45 • “generate-schema (SchemaGenerator)” on page 46
bv-updater The bv-updater utility imports, updates, and deletes content information or category information into your BroadVision content database. The utility processes data contained in XML files. For example, you can use this utility to specify content database actions to insert rows, remove rows, update rows, or replace rows. For detailed instructions on using bv-updater, see “bv-updater” in the appendices.
set-db The bvtool set-db command changes the database settings for your BroadVision system. The syntax is: bvtool set-db -user db-user -passwd db-password -database db-name -server server-name -url jdbc-url
bv-xmldumper Use bvtool bv-xmldumper to perform a BroadVision content or category dump into XML files. You must provide: • the full path to the configuration file (.txt) • the full path to the XML data file into which you are dumping the data For example: -c yourPath/config_file -f yourPath/xml_data_file Inside the config file, the following variables may be set: log= (the default log file is DumpMain.log in the current directory) lc_number=_ (locale to parse the number from XML file) lc_datetime=_ (locale to parse the datetime from XML file)
The machine default locale will be used if you do not specify the above locales. Content Guide
45
Ch apter 4 Too ls and Utili ti es for Worki ng with Conten t Co nte nt Man age me nt an d Bulk Loa ding T ool s
generate-schema (SchemaGenerator) The generate-schema command is used to create SQL scripts from your XML schema files. The SQL scripts can then be executed to create or update tables in your database. Use bvtool generate-schema to generate SQL files for content types. IMPORTANT: You cannot alter existing column types using generate-schema.
First, set BroadVision environment variables by executing, or sourcing, the install_dir/bin/setEnv utility for your operating system. Then execute bvtool with the following syntax: bvtool generate-schema -schema xmlFile -script sqlFile -vendor dbVendor [-noextension]
or bvtool generate-schema -propFile propertiesFile -vendor dbVendor [-noextension] -schema xmlFile The name of the schema XML file to use as input. -script sqlFile The name of the SQL file to generate. -vendor dbVendor The name of your database vendor: oracle, microsoft, mysql, informix, db2,
hsqldb. -noextension Generates the SQL for an entire content type or profile. Use this option when creating new content types. Do not use this option when adding attributes to an existing content type or profile table. -propFile propertiesFile A properties file with entries formatted as follows: xmlFilePath=sqlFilePath
Use this option to generate SQL files for multiple XML schemas at one time. See spec_list1.properties in the install_dir/setup/bvf directory for an example of a properties file. This example creates an SQL script for adding attributes to the Editorial content type for an Oracle database: bvtool generate-schema -schema edit_spec.xml -script edit_spec.sql -vendor oracle
This example creates an SQL script for a new attribute type for an Informix database. See cnt_type.xml in the install_dir/setup/install/srcxml.us directory for an example of the file syntax: bvtool generate-schema -schema my_custom_type.xml -script my_custom_type.sql -vendor informix -noextension
46
BroadVision, Inc.
Chap te r 4
Tool s an d Uti lities fo r Working wi th Co ntent C ontent Ma nag ement a nd Bulk Lo adin g Too ls
BroadVision Management Center The BroadVision Management Center is bundled with Portal. It provides a way to manage information in a portal application. You can enter and edit information in the database and also create a personalized experience for your site visitors. The BroadVision Management Center allows you to establish logic to select the content you want to display to visitors of your site.
Tasks are divided into nine groups that correspond to nine tabbed pages, depending upon the licenses you have:
Content Guide
Tab
Purpose
Service
Administer caches, microsite templates, and single-sign on for your service. To use this tab, you need the Service Administrator role.
Users
Manage user templates, groups of users, and user profiles for site visitors. To use this tab, you need the User Administrator or Organization Administrator role.
Navigation
Manage the navigation and presentation of a portal site, including channels, programs, portlets, and page types. To use this tab, you need the Navigation Administrator or Channel Administrator role.
Process
Configure process packs, models, or instances. Reassign or delegate tasks and roles. To use this tab, you need the Process Administrator, Pack Deployer, or Process Manager role.
Personalization
Manage qualifiers, segments, rule sets, email notifications, and alert notifications. To use this tab, you need the Personalization Administrator role.
Content
Categorize and create content, manage document types, define content roles, and assign users and groups to content roles. To use this tab to perform these types of tasks, you need the Content Administrator role.
47
Ch apter 4 Too ls and Utili ti es for Worki ng with Conten t Co nte nt Man age me nt an d Bulk Loa ding T ool s
Tab
Purpose
My Work
View tasks that are assigned to you and process instances that you created.
Staging
Ship and receive content, view orders, set staging preferences.
Orders
Perform searches for orders, create Process instances, confirm orders, create order flows.
Your administrator performs the tasks associated with content in the BroadVision Management Center. For information, refer to the Portal Administrator Guide.
Inline Publishing If a Portal administrator grants permissions, a user may publish content directly by using the Portal site. BroadVision Portal sites support publishing four kinds of content: editorials, advertisements, URLs, and products. To learn about the publishing process for each of these types, consult the Portal User Guide.
48
BroadVision, Inc.
Chap te r 4
Tool s an d Uti lities fo r Working wi th Co ntent O th er Too ls
Other Tools Besides the tools used to bulk-load content into your BroadVision database, you should understand how to use other utilities that assist you when working with content. For additional information about the tools, see the guides referred to in each respective section.
bvant The bvant utility is a BroadVision Java-based utility that uses XML build files to: • manually set up installed BroadVision software • pre-compile JSPs in a .war file • generate XSD schemas from database tables • generate publishing processes for content types The primary reasons for using bvant are to: • exercise more control over the deployment of process packs • debug deployment or setup by displaying more information than is provided by other utilities • re-compile the BroadVision Management Center and sample application JSPs to shorten the application server start-up time See the BroadVision 8.2 Installation Guide and Process Services Developer Guide for more information.
generate_xsd You can use the generate_xsd.xml file with the bvant command to automatically generate an XSD schema file based on a SQL database table or BroadVision content type that you specify.
bv-param.xml To configure the content types that appear in the BroadVision Management Center when managing programs, you use the bv.portal.tool.content.PROGRAM_CONTENT_TYPES parameter in the install_dir/baseSuites/bv_services/modules/svc_clt/bv-param.xml file. Use bvtool set-param to update the parameter. Also use this utility to configure the column to use the display name for content items. See “Configuring Content Types” on page 94 for additional information.
ext_cnt_config.xml Use this utility to specify a new data source. Located in config_dir /appConfig/bv_framework.
Content Guide
49
Ch apter 4 Too ls and Utili ti es for Worki ng with Conten t Oth er T ool s
50
BroadVision, Inc.
5
Using the API
Most often, your development efforts will focus on using the application layer interfaces. However, sometimes you may need to develop your own custom components. This section gives an overview of the Data Access API. Additionally, you can consult the Javadoc that comes with your product. This chapter contains the following topics: • “API Overview,” next • “Content Data and Caching” on page 53 • “Data Access Packages” on page 54 • “Class Overviews” on page 55 • “Interfaces” on page 66
Content Guide
51
Ch apter 5 Using the API API Overview
API Overview The primary purpose of the Data Access API is to access content or category data, execute generic database queries or updates, and update the database. As described in previous chapters of this guide, you use content to display information to users, categorize it for organization, and use the database to store it. While data is stored in a relational database, programs treat it as objects. When a DataAccess API retrieves a content item from the database, it extracts the information contained in the desired row of a particular table and packages it as an object. The information contained in the individual fields, defined by the columns, become attributes (or properties) of the object: The following diagram depicts some of the classes frequently used when working with content and their relationship to a database table. Notice that DataManager is used to retrieve content from the database and get Content and Category information. TableData acts as an object that contains rows of database information. RowData and DataValue each help to comprise TableData.
The DataManager class accesses data via EJBs. It retrieves content and category objects.
The TableData class can be viewed as an object containing a number of rows with the same columns and containing a list of RowData
The Content class represents an object that has been defined as a content item in the system
OID
PROD_ID
STORE_ID
NAME
CREATION_TIME
8266
123modem
91
Next Gen DSL Modem
2008-01-17 11:53:44.90000000
8267
cell7418
91
7418 Cell Phone
2008-01-17 11:53:44.90000000
The RowData class contains a list of DataValue objects and attribute names. DataValue should consist of a BroadVision Primitive type and a value. (TableData is like a list of RowData.)
The classes in the diagram and the packages in which they reside are described in more depth in this chapter.
52
BroadVision, Inc.
C hapter 5 Usin g the API Conten t Data and Ca chin g
Content Data and Caching Cache flushing takes place by default when a BroadVision API is called that updates the database. The default behavior can be changed by changing the values on the CallSetting object (see “CallSettings” on page 65). Caches for content items exist in the Enterprise JavaBean (EJB) container as well as the web tier or servlet container. There is at most one cache object per content item in the EJB cache or the webcache. For content items, cache flushing is synchronous for the local EJB cache and asynchronous for caches elsewhere in other JVMs. Visitor profile is cached in the EJB container only. A content or visitor object fetches data using an API call. One of the following scenarios occurs when a content object fetches data: • If the API call does not request read-through and the object exists in the cache, it retrieves data from the cache. If the object is not in the cache, then data is read from the database and placed in the cache. • If an API requests read through, then the database is accessed immediately and the cache is updated. When a save() method is called, updated values are written to the database. Depending on values of the applicable CallSetting object, the cache entry for the object is flushed so that the next request for the object reads it directly from the database. Note that cached copies are never modified. When updates occur, the cached copy is flushed and refreshed using database data. If a copy remains in the web tier, it is stale until the object is fetched again. List tables are cached when the application specifically requests data from that list table. The following methods in the Content class flush the cache: • save() • appendListData() • deleteListData() • modifyListData() • replaceListData() • replaceQualifierValues() • update() • delete()
The following methods in the DataManager class flush the cache: • deleteContent() • deleteContents() • deleteCategory() • updateContent() • updateContents() • updateCategory() • createCategory() • moveCategory()
Content Guide
53
Ch apter 5 Using the API Da ta Access Pa ckages
Data Access Packages Classes that you commonly need to perform tasks associated with content and content management include those in the following packages. These packages are found within the Data Access API: • com.broadvision.data.common—contains classes that represent and organize data. The classes that you will commonly use include TableData, RowData, PrimitiveType, DataValue, ContentData, ContentKey, ContentUID, and CallSettings. • com.broadvision.data.client—for working with content, categories, and retrieving content and category objects. The classes you will commonly use include Content and Category. • com.broadvision.data.exceptions—for working with database error exceptions. • com.broadvision.data.sql—contains classes that define SQL conditions, list SQL expressions, represent SQL expressions, etc. • com.broadvision.data.cache—for working with data caches. NOTE: You will not typically use com.broadvision.data.cache.
The most frequently used classes you will access are described in the remainder of this chapter. For additional information and a complete listing of classes and their methods, see your Javadoc.
54
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
Class Overviews This section contains overviews and examples of the classes you will frequently use in the Data Access API. Reference your Javadoc for additional detail about these classes as well as information about other classes in the Data Access API. Classes described include: • “DataManager” on page 56 • “Content” on page 57 • “Category” on page 58 • “TableData” on page 59 • “RowData” on page 60 • “DataValue” on page 61 • “ContentData” on page 62 • “ContentKey” on page 63 • “ContentUID” on page 64 • “CallSettings” on page 65 • “PrimitiveType” on page 65
Content Guide
55
Ch apter 5 Using the API Class Overviews
DataManager When working with content, you must use DataManager for accessing your data. This class saves you development time because it acts as a wrapper so that you do not have to create database connections. DataManager calls com.broadvision.data.client.DataManagerImpl, which performs the actual implementation. For instance, if you want to retrieve a content item, use must use DataManager: public static Content contentByUID(String typename, String servicename, long oid) { Content cnt = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, oid); // There must be a Data Manager DataManager mgr = new DataManager(); // Retrieve the content from the DataManager cnt = mgr.getContent(uid); } catch (ContentNotFoundException cnfe) { } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cnt; } NOTE: The default behavior is to display both online and offline content. You can use a method call
to specify the display of online content only. To retrieve online category content only, create the content UID and set your content status. ContentUID catKey = new ContentUID( serviceId, categoryOID, contentTypeName); Category category = _cntMgr.getCategory(catKey); category.getCallSettings().setInterestedContentStatus (DataConstants.BV_ONLINE_DB_CONTENT); List childContent = category.getMemberContents( null, null, getContentTypeId (),true);
The methods that you can invoke include those that work with • categories – check if categories exists, delete categories • content – check if content exists, create relationships, delete relationships, delete content, obtain information about attributes • database – update data in the database, delete data, execute SQL operations • multivalue tables – delete entries from a related list table • queries – check if a content item exists Also see “Content Data and Caching” on page 53.
56
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
Content Content represents a content item. When working with Content, you can perform actions to retrieve content from your database, find out information about content, and also alter the content displayed to users. Content implements two interfaces—ExtendedAttributes and IQualifierValue. (For information about these interfaces, see “Interfaces” on page 66.)
IQualifierValue
Content
ExtendedAttributes
Here the getContentTypeId and getServiceId methods are invoked to find a content item to delete: public static Content contentByUID(String typename, String servicename, long oid) { Content cnt = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, oid); // There must be a Data Manager DataManager mgr = new DataManager(); // Retrieve the content from the DataManager cnt = mgr.getContent(uid); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cnt; }
The methods that you can invoke include those that work with • categories – change status of categories, create child categories • content – create persistent content, save content after modification, update content, get an OID • multivalue tables – append list tables • queries – get service ID information, check to see if an item is deleted, check if an input is null Also see “Content Data and Caching” on page 53.
Content Guide
57
Ch apter 5 Using the API Class Overviews
Category Category extends Content and is similar to a Content object. A category can have attributes, may contain list tables, etc. A group of categories make up a category tree. Additionally, a category has structural properties attached to it because it exists as part of a tree-structure (or a node in a tree). Because of this, a category contains methods for retrieving node-based information, as well as information similar to its content counterpart. Each category is uniquely identified by a Content UID or a Content Key.
IQualifierValue
Content
ExtendedAttributes
Category
In this example, you retrieve content based on the getMemberContents method, which looks for content within a category: public static List contentInCategoryByCondition(Category cat, String table, String column, SQLOperator op, DataValue value, String typename) { List lst = null; try { // Build the condition SQLCondition cond = SQLConditionFactory.buildCondition(table, column, op, value); // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Look in Category for Contents matching Condition lst = cat.getMemberContents(null, cond, typeId, false); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } return lst; }
The methods that you can invoke for Category include those that work with • categories – add items to categories, create categories, save category after modification • queries – find category members, find root OID of category
58
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
TableData TableData contains a list of RowData and represents a table of data with a fixed number of columns after construction. TableData can be viewed as an object containing a number of rows with the same columns. The TableData constructor creates a table in memory with a name. Once
this table is created, you can append rows to it. The first row of data determines the size and attribute names for the remaining rows. You can use TableData to work with multivalue attributes. (See “Multivalue Attributes” on page 19.) For example, here a multivalue list named “MYLISTNAME” is retrieved using TableData: try TableData tblData = myContent.getListData(“MYLISTNAME”); if (tblData.size() == 0) { log(“No rows returned.”); } else { log(“# of rows = “ + tblData.size()); } }catch(DataException e) { ... }
The methods that you can invoke for TableData include those that work with • tables – append columns and rows and change attribute names, create new tables using existing table columns, work with multivalue tables • multivalue tables – retrieve multivalue lists, find multivalue lists • queries – find all rows in a table with matching attribute-values, get list of attributes, return column values
Content Guide
59
Ch apter 5 Using the API Class Overviews
RowData RowData represents a list of DataValue objects and attribute names. You can create new content by using RowData, as shown below. Create a contentRow object consisting of RowData, which consists of DataValues that are mapped to strings representing attributes. (To see how RowData is created, see “Insert Row in a Content Multivalue Table” on page 75.) public static ContentUID createContent(String typename, String servicename, Category cat, RowData contentRow) { ContentUID uid = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create a ContentData object for the Content ContentData data = new ContentData(typeId, storeId, contentRow, null); // There must be a Data Manager DataManager mgr = new DataManager(); // Get the ContentKey if (cat != catKey }
ContentKey of the Category if it exists catKey = null; null) { = cat.getKey();
// Create the Content using the ContentData for the Content // and the ContentKey of the Category to create the Content in uid = mgr.createContent(data, catKey); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } return uid; }
The methods that you can invoke for RowData include those that work with rows to append rows, return rows, remove column names and values from rows, filter row data, get and set row data.
60
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
DataValue DataValue should consist of a BroadVision PrimitiveType and a value. You can use DataValue
when setting attributes within content. Once objects are created, the values cannot be changed. Below, DataValue is used to create an object with a primitive type as the parameter. If you want to use a custom type, refer to DataType in your Javadoc. public static void setContentAttributeUsingSetValue(Content content, String name, DataValue value) { // Set the value of the Content content.setValue(name, value); try { // Save the content to the database content.save(); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } }
The methods that you can invoke for DataValue include those that work with data to retrieve types, compare objects and values, check for equivalent values.
Content Guide
61
Ch apter 5 Using the API Class Overviews
ContentData Represents an object that has been defined as a content item. These objects must be retrieved using DataManager. (See “Class Overviews” on page 55 for information and example.) In this code example, ContentData is used to create a new object after DataManager retrieves the content type ID and Service ID. public static ContentUID createContent(String typename, String servicename, Category cat, RowData contentRow) { ContentUID uid = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create a ContentData object for the Content ContentData data = new ContentData(typeId, storeId, contentRow,null); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the Content using the ContentData for the Content // and the ContentKey of the Category to create the Content in uid = mgr.createContent(data, null); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } return uid; }
The methods that you can invoke for ContentData include those that work with • content – get content type ID, get service ID, get attribute types, set values and types • multivalue tables – get all multivalue table entries
62
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
ContentKey ContentKey represents the BroadVision key object. (Refer to “Content Key” on page 25.) You will use ContentKey often while performing actions to access content, including content within specific categories. In the following example, a new ContentKey object is created to be passed in as a parameter to the getCategory method. public static Category getCategory(String typename, String servicename, String path) { Category cat = null; try { // Retrieve the Category Service ID int storeId = DataManager.getServiceId(servicename); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the ContentKey for the Category ContentKey catKey = new ContentKey(storeId, path, typename); // Retrieve the Category from the DataManager cat = mgr.getCategory(catKey); } catch (CategoryNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cat; }
The methods that you can invoke include those that work with queries to get type ID, get service ID.
Content Guide
63
Ch apter 5 Using the API Class Overviews
ContentUID ContentUID represents content items and category nodes by uniquely identifying them using type ID, service ID, and OID. In the example here, a content item is being retrieved using ContentUID after first creating it. public static Content contentByUID(String typename, String servicename, long oid) { Content cnt = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, oid); // There must be a Data Manager DataManager mgr = new DataManager(); // Retrieve the content from the DataManager cnt = mgr.getContent(uid); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cnt; }
The methods that you can invoke include those that work with queries to get/set OIDs, get serviceId, get typeId.
64
BroadVision, Inc.
C hapter 5 Usin g the API Class Overviews
CallSettings CallSettings is used to control settings in the DataManager, Content and Category APIs. In this example, using CallSettings allows you to avoid the cache so that information can be retrieved more quickly. CallSettings dmCallSettings = new CallSettings(); dmCallSettings.setReadThroughFlag(true); dmCallSettings.setNoCacheFlushFlag(false); DataManager dataMgr = new DataManager(visitorId); dataMgr.setCallSettings(dmCallSettings);
The methods that you can invoke for CallSettings include those that work with • online/offline status • qualifiers – set/unset filtering • maximum items to be returned
PrimitiveType PrimitiveType defines the following BroadVision-specific data values: • STRING – a type string • LONG – a type long • MONEY – a type money • DATETIME – a date/time type • DOUBLE – a type double • ENUM – an enumerated type • DICT – a number/name pair list that is not necessarily consecutive
• OID – an OID type; see “OID” on page 25 • INT – a type integer • Clob – a database clob type • BOOLEAN – a boolean type • TEXT – a text type NOTE: As of 8.1, BYTEARRAY—a byte array type—is not supported.
Content Guide
65
Ch apter 5 Interfaces
Using the API
Interfaces Content implements two interfaces, which are discussed in this section. • “ExtendedAttributes” on page 66 • “IQualifierValue” on page 66
ExtendedAttributes This interface enables BroadVision objects to access their fields using a map-like process. Fields are accessed by name, and the appropriate typed method is called to get the desired data type. This interface also contains methods that check the data type of a particular attribute of an object.
IQualifierValue This interface specifies the methods required for data and profile objects that support qualifierbased filtering. The methods are used to retrieve and set qualifier values for data and profile objects. See the Portal Administrator Guide for information about working with qualifiers.
66
BroadVision, Inc.
6
Examples
The examples in this chapter offer an overview of some of the basic APIs, why you would use them, and code snippets. For additional information about BroadVision APIs, consult your Javadoc. This chapter contains the following topics: • “Basic Content Examples,” next • “Working with Multivalue Tables” on page 73 • “Setting Attributes and Rows” on page 79 • “Working with Categories” on page 87
Content Guide
67
Ch apter 6 Exa m ples Basic Con te nt Exampl es
Basic Content Examples This section contains examples of using the Data Access API to work with content in fundamental ways. The examples include: • “Create New Content” on page 69 • “Delete Content” on page 70 • “Retrieve Content Using ContentUID ” on page 71 • “Retrieve Content Using ContentKey as the Key” on page 72
68
BroadVision, Inc.
Chap te r 6 Exampl es Basic Con te nt Exampl es
Create New Content There are multiple ways in which you can create new content in the database. The example below is just one method. Here, ContentData is used to create a new content object. Notice that first DataManager is used to retrieve content information (see “Class Overviews” on page 55). Steps:
1. Retrieve Type ID using the known content type. 2. Retrieve Service ID using the known service. 3. Create new ContentData object using Type ID and Service ID. 4. Create new content using ContentData and ContentKey.
public static ContentUID createContent(String typename, String servicename, Category cat, RowData contentRow) { ContentUID uid = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create a ContentData object for the Content ContentData data = new ContentData(typeId, storeId, contentRow, null); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the Content using the ContentData for the Content // and the ContentKey of the Category to create the Content in uid = mgr.createContent(data, null); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } return uid; }
Content Guide
69
Ch apter 6 Exa m ples Basic Con te nt Exampl es
Delete Content In this example, DataManager is used to retrieve a content item before invoking the deleteContent method to delete it. Steps:
1. Retrieve Type ID using the known content type. 2. Retrieve Service ID using the known service. 3. Create Content UID using Service ID, Type ID, and OID. 4. Delete Content using Content UID. public static void deleteContent(String typename, String servicename, long oid) { try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, oid); // Delete the Content using the Data Manager mgr.deleteContent(uid); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
70
BroadVision, Inc.
Chap te r 6 Exampl es Basic Con te nt Exampl es
Retrieve Content Using ContentUID Recall from “Content UID” on page 26 that every content item in the database has a unique content UID that consists of three fields—the content type ID, service ID, and OID. Suppose you want to find a content item and you know the OID already. You could perform the following steps, where you call the getContent method in DataManager and pass in the UID. Steps:
1. Retrieve Type ID using the known content type. 2. Retrieve Service ID using the known service. 3. Create Content UID using Service ID, Type ID, and OID. 4. Retrieve Content using Content UID. public static Content contentByUID(String typename, String servicename, long oid) { Content cnt = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, oid); // There must be a Data Manager DataManager mgr = new DataManager(); // Retrieve the content from the DataManager cnt = mgr.getContent(uid); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cnt; }
Content Guide
71
Ch apter 6 Exa m ples Basic Con te nt Exampl es
Retrieve Content Using ContentKey as the Key Every content item in the database has a content key. You may need to retrieve content using a content key because you do not know the content’s OID. You could perform the following steps, where, as in the previous example, you call the getContent method in DataManager. However, this time you are passing in a parameter representing the content key for retrieval. NOTE: Content keys are often used instead of content UID. You need to specify the type ID, service
ID, and either a String or data value. Steps:
1. Retrieve Type ID using the known content type. 2. Retrieve Service ID using the known service. 3. Create ContentKey using Service ID, Type ID, and key. 4. Retrieve Content using ContentKey. public static Content contentByKey(String typename, String servicename, String key) { Content cnt = null; try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Retrieve the Content Service ID int storeId = DataManager.getServiceId(servicename); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the ContentKey ContentKey ckey = new ContentKey(typeId, storeId, key); // Retrieve the Content from the DataManager cnt = mgr.getContent(ckey); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cnt; }
72
BroadVision, Inc.
Chap te r 6 Exampl es W orking w ith Mul ti value T abl es
Working with Multivalue Tables Since many content items will be associated with multivalue tables, it is useful to see examples of how to create values for these tables, how to insert content into them, and how to properly delete information. For additional information about how multivalue attributes and tables are structured, refer to “Multivalue Attributes” on page 19. This section contains the following examples: • “Create a Multivalue Table” on page 74 • “Insert Row in a Content Multivalue Table” on page 75 • “Delete Row in a Content Multivalue Table” on page 76 • “Update a Content Multivalue Table” on page 77 • “Save a Content Item’s Multivalue Data” on page 78
Content Guide
73
Ch apter 6 Exa m ples W orking with Multival ue Ta ble s
Create a Multivalue Table You can use TableData to create a multivalue table. (Refer to “TableData” on page 59 for information about using TableData with multivalue tables.) This example uses RowData to build a specific multivalue table. Steps:
Chap te r 6 Exampl es W orking w ith Mul ti value T abl es
Insert Row in a Content Multivalue Table In “Multivalue Attributes” on page 19, the example contains a multivalue table that lists color choices. Perhaps your manufacturer now offers additional colors, and you need to make the options available to related products. You can use Content’s update method, a method that updates multivalue tables to perform this task. Steps:
1. Create RowData representing the new row by using the list of new names and new values. 2. Record the insertion to a ListUpdater object using RowData and the name of the list table to which you want to insert. 3. Make sure the content to update the list with is not dirty. 4. Insert into the list table using ListUpdater. public static void insertToContentList(Content content, String listname, List newnames, List newvalues) { try { // Create a RowData using the newnames and newvalues lists RowData newRow = new RowData(newnames, newvalues); // Create a ListUpdater ListUpdater toUpdate = new ListUpdater(); // Record the insertion with the ListUpdater toUpdate.recordInsert(listname, newRow); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Perform the update content.update(null, toUpdate); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
Content Guide
75
Ch apter 6 Exa m ples W orking with Multival ue Ta ble s
Delete Row in a Content Multivalue Table The steps to delete a row in a multivalue table are similar to inserting a row in a multivalue table. Steps:
1. Create RowData representing the row using the List of new names and new values. 2. Record the insertion to a ListUpdater object using RowData and the name of the list table to which to insert. 3. Update the multivalue table using ListUpdater. 4. Make sure the content to update the list is not dirty. 5. Perform the delete. public static void deleteFromContentList(Content content, String listname, List keynames, List keyvalues) { try { // Create a RowData using the keynames and keyvalues lists RowData keyRow = new RowData(keynames, keyvalues); // Create a ListUpdater ListUpdater toUpdate = new ListUpdater(); // Record the deletion with the ListUpdater toUpdate.recordDelete(listname, keyRow); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Perform the deletion content.update(null, toUpdate); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
76
BroadVision, Inc.
Chap te r 6 Exampl es W orking w ith Mul ti value T abl es
Update a Content Multivalue Table You can perform an update to a multivalue table by using Content’s update method. Steps:
1. Create RowData representing the keys using the List of key names and key values. 2. Create RowData representing the target using the List of target names and target values. 3. Record the update to a ListUpdater object using the two RowData objects and the name of the list table to update. 4. Make sure the Content to update the list is not dirty. 5. Update the list table using the ListUpdater. public static void updateContentList(Content content, String listname, List keynames, List keyvalues, List targetnames, List targetvalues) { try { // Create a RowData using the keynames and keyvalues lists RowData keyPairs = new RowData(keynames, keyvalues); // Create a RowData using the targetnames and targetvalues lists RowData targetPairs = new RowData(targetnames, targetvalues); // Create a ListUpdater ListUpdater toUpdate = new ListUpdater(); // Record the update with the ListUpdater toUpdate.recordUpdate(listname, keyPairs, targetPairs); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Perform the update content.update(null, toUpdate); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
Content Guide
77
Ch apter 6 Exa m ples W orking with Multival ue Ta ble s
Save a Content Item’s Multivalue Data When you create new multivalue data for a content item, you will likely want to save it. This example is one way in which you can do so by using TableData to represent the new data. Steps:
1. Create TableData representing the multivalue table. 2. Set your attributes. 3. Save. TableData tbl = new TableData(“BV_PROD_TRANSLATE”); RowData row = new RowData(); row.setStringValue(“LANGUAGE”, “french”); row.setStringValue(“NAME_TRANSLATE”, “french name”); row.setStringValue(“SDESC_TRANSLATE”, “french sdesc”); row.setStringValue(“LONGDESC_TRANSLATE”, “french longdesc”); log(“saving bv_prod_translate with 1 row...”); try { myContent.setListData(“BV_PROD_TRANSLATE”, tbl); myContent.save(); getListData(“BV_PROD_TRANSLATE”); } catch (Exception e) { log(“exception: “ + e.getMessage()); e.printStackTrace(); }
78
BroadVision, Inc.
Chap te r 6 Exampl es Se ttin g Attributes and Ro ws
Setting Attributes and Rows There are various ways in which you can set specific values for content items as well as set rows. This section contains the four examples: • “Set an Attribute Value Within Content Using setValue()” on page 80 • “Set an Attribute Value Within Content Using update()” on page 81 • “Set Parent Row for Content” on page 82 • “Update Main Row of Content, Queue Series of Content List Update Records, and Perform Updates Concurrently” on page 83
Content Guide
79
Ch apter 6 Exa m ples Setting Attrib utes a nd Row s
Set an Attribute Value Within Content Using setValue() You can use the setValue method in Content to set the value of a single attribute in a table. For example, perhaps you are creating a new content type, and one of the column names should be PRICE. You can use code similar to the below to set your attribute. Steps:
1. Set the value of the content attribute using the name of the attribute and the value to which to set the attribute. 2. Save the content. public static void setContentAttributeUsingSetValue(Content content, String name, DataValue value) { // Set the value of the Content content.setValue(name, value); try { // Save the content to the database content.save(); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } }
80
BroadVision, Inc.
Chap te r 6 Exampl es Se ttin g Attributes and Ro ws
Set an Attribute Value Within Content Using update() You can use the update method in Content to update the existing value of a single attribute in a table. For example, perhaps the value of your attribute PRICE is $10.00 and you want to change it to $50.00. You can use code similar to the below to update the attribute. Steps:
1. Create a List for the name of the attribute to update. 2. Create a List for the value to update. 3. Create RowData out of the two lists. 4. Make sure the content to update is not dirty. 5. Update the content with RowData. public static void setContentAttributeUsingUpdate(Content content, String name, DataValue value) { // Create the attribute to update ArrayList attribute = new ArrayList(); attribute.add(name); // Create the value to update to ArrayList val = new ArrayList(); val.add(value); try { // Create the RowData update RowData toUpdate = new RowData(attribute, val); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Perform the update content.update(toUpdate, null); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
Content Guide
81
Ch apter 6 Exa m ples Setting Attrib utes a nd Row s
Set Parent Row for Content This example sets the primary row for a content item. Steps:
1. Create RowData to to use for update by using the list of names and list of values to update. 2. Make sure the content to update is clean. 3. Update the content. public static void setContentMainRow(Content content, List names, List values) { try { // Create the RowData update RowData toUpdate = new RowData(names, values); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Perform the update content.update(toUpdate, null); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } }
82
BroadVision, Inc.
Chap te r 6 Exampl es Se ttin g Attributes and Ro ws
Update Main Row of Content, Queue Series of Content List Update Records, and Perform Updates Concurrently In this example, the PRICE and STOCK attributes of the main row are being updated to 50.00 and 5 and then inserted into BV_PROD_TRANSLATE in four rows for four separate languages. Afterward, the row with NAME_TRANSLATE set to “Hola” is deleted and LONGDESC_TRANSLATE is updated for all rows with SDESC_TRANSLATE set to “A Greeting.” Steps:
1. Create the list of attributes for the main row update. 2. Create the list of values for the main row to be updated. 3. Create the list of columns for the insertion operations. 4. Create the lists for the values belonging to the four rows to insert. 5. Create two lists for the key for deletion. 6. Create two lists for the key for update. 7. Create two lists for the target for update. 8. Create RowData out of the lists. 9. Create a ListUpdater and queue up four insert operations using the four RowData objects to insert, a delete operation using the key RowData for the deletion, and an update operation using the key and target RowData for the update. 10. Make sure the content that is to be updated is not dirty. 11. Update the content using RowData containing the main row update and the ListUpdater.
Content Guide
83
Ch apter 6 Exa m ples Setting Attrib utes a nd Row s
// List of main row attributes to update ArrayList attributes = new ArrayList(); attributes.add("PRICE"); attributes.add("STOCK"); // List of main row values to update to ArrayList newvalues = new ArrayList(); newvalues.add(new DataValue(50.00)); newvalues.add(new DataValue(5)); // List of columns within the BV_PROD_TRANSLATE table ArrayList names = new ArrayList(); names.add("LANGUAGE"); names.add("NAME_TRANSLATE"); names.add("SDESC_TRANSLATE"); names.add("LONGDESC_TRANSLATE"); // List of data for the BV_PROD_TRANSLATE table ArrayList values1 = new ArrayList(); values1.add(new DataValue("English")); values1.add(new DataValue("Hi")); values1.add(new DataValue("A Greeting")); values1.add(new DataValue("Long Description of Hi")); // List of data for the BV_PROD_TRANSLATE table ArrayList values2 = new ArrayList(); values2.add(new DataValue("Chinese")); values2.add(new DataValue("Ni Hao")); values2.add(new DataValue("A Greeting")); values2.add(new DataValue("Long Description of Ni Hao")); // List of data for the BV_PROD_TRANSLATE table ArrayList values3 = new ArrayList(); values3.add(new DataValue("Japanese")); values3.add(new DataValue("Konichiwa")); values3.add(new DataValue("A Greeting")); values3.add(new DataValue("Long Description of Konichiwa")); // List of data for the BV_PROD_TRANSLATE table ArrayList values4 = new ArrayList(); values4.add(new DataValue("Spanish")); values4.add(new DataValue("Hola")); values4.add(new DataValue("A Greeting")); values4.add(new DataValue("Long Description of Hola")); // Column name for a key to BV_PROD_TRANSLATE table ArrayList key1 = new ArrayList(); key1.add("NAME_TRANSLATE"); // Value for a key to BV_PROD_TRANSLATE table ArrayList keyval1 = new ArrayList(); keyval1.add(new DataValue("Hola")); // Column name for a key to BV_PROD_TRANSLATE table
84
BroadVision, Inc.
Chap te r 6 Exampl es Se ttin g Attributes and Ro ws
ArrayList key2 = new ArrayList(); key2.add("SDESC_TRANSLATE"); // Value for a key to BV_PROD_TRANSLATE table ArrayList keyval2 = new ArrayList(); keyval2.add(new DataValue("A Greeting")); // Column name to BV_PROD_TRANSLATE table ArrayList target1 = new ArrayList(); target1.add("LONGDESC_TRANSLATE"); // Value to change to ArrayList targetval1 = new ArrayList(); targetval1.add(new DataValue("Generic Long Description")); try { // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId("PRODUCT"); // Retrieve the Content Service ID int storeId = DataManager.getServiceId("C3"); // Create the ContentUID ContentUID uid = new ContentUID(typeId, storeId, 8258); // There must be a Data Manager DataManager mgr = new DataManager(); // Retrieve the content from the DataManager Content content = mgr.getContent(uid); // Create a new ListUpdater ListUpdater toUpdate = new ListUpdater(); // Create the RowData for updates to the main row RowData main = new RowData(attributes, newvalues); // Create the RowData to insert RowData row1 = new RowData(names, RowData row2 = new RowData(names, RowData row3 = new RowData(names, RowData row4 = new RowData(names,
values1); values2); values3); values4);
// Create the key RowData for deletion RowData keyrow1 = new RowData(key1, keyval1); // Create the key and target RowData for update RowData keyrow2 = new RowData(key2, keyval2); RowData targetrow1 = new RowData(target1, targetval1); // Record the insertions with the ListUpdater toUpdate.recordInsert("BV_PROD_TRANSLATE", row1);
Content Guide
85
Ch apter 6 Exa m ples Setting Attrib utes a nd Row s
toUpdate.recordInsert("BV_PROD_TRANSLATE", row2); toUpdate.recordInsert("BV_PROD_TRANSLATE", row3); toUpdate.recordInsert("BV_PROD_TRANSLATE", row4); // Record the update with the ListUpdater toUpdate.recordUpdate("BV_PROD_TRANSLATE", keyrow2, targetrow1); // Record the deletion with the ListUpdater toUpdate.recordDelete("BV_PROD_TRANSLATE", keyrow1); // Make sure the content isn't dirty if (content.isDirty()) content.save(); // Update the content content.update(main, toUpdate); } catch (ContentNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); }
86
BroadVision, Inc.
Chap te r 6 Exampl es Workin g with Categori es
Working with Categories Categories help you to organize your content in logical groups (refer to “Categories” on page 27). The examples in this section show how you can use the Data Access API to work with category information. The following examples are included: • “Retrieve a Category” on page 88 • “Create New Category” on page 89 • “Retrieve List of Content within a Category Matching a Given Set of Conditions” on page 90 • “Add Members to a Category” on page 91 • “Create Child Category” on page 92
Content Guide
87
Ch apter 6 Exa m ples W orking with Categ ories
Retrieve a Category You will often need to retrieve categories for your users. For example, perhaps you want your users to be able to look up all of the styles of cell phones that you sell. For example, you could retrieve the content that falls into the category named cellular. One way to retrieve a category is to use the getCategory method in DataManager and pass in a parameter representing the content key. Steps:
1. Retrieve Service ID using the known service. 2. Create ContentKey for Category using Service ID, path of the Category, and name of content type serviced by the Category. 3. Retrieve Category using ContentKey. public static Category getCategory(String typename, String servicename, String path) { Category cat = null; try { // Retrieve the Category Service ID int storeId = DataManager.getServiceId(servicename); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the ContentKey for the Category ContentKey catKey = new ContentKey(storeId, path, typeame); // Retrieve the Category from the DataManager cat = mgr.getCategory(catKey); } catch (CategoryNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cat; }
88
BroadVision, Inc.
Chap te r 6 Exampl es Workin g with Categori es
Create New Category It is likely that at some point you will need to create a new category for your content. For example, perhaps you need to create a category for a new type of telephone that you previously did not sell. To create a new category use the createCategory method in DataManager. Steps:
1. Retrieve Service ID using the known service. 2. Create ContentKey for Category using Service ID, path of the new Category, and name of content type serviced by the Category. 3. Create Category using ContentKey. public static Category createCategory(String typename, String servicename, String path) { Category cat = null; try { // Retrieve the Category Service ID int storeId = DataManager.getServiceId(servicename); // There must be a Data Manager DataManager mgr = new DataManager(); // Create the ContentKey for the Category ContentKey catKey = new ContentKey(storeId, path, typename); // Create the Category with the DataManager cat = mgr.createCategory(catKey, null); } catch (CategoryNotFoundException cnfe) { // Do nothing } catch (DataException de) { // Other unexpected exceptions should get logged. de.printStackTrace(); } return cat; }
Content Guide
89
Ch apter 6 Exa m ples W orking with Categ ories
Retrieve List of Content within a Category Matching a Given Set of Conditions You may need to retrieve the list of content within a specific category based on a certain condition. Maybe you would like to retrieve all content within the Product category that has to do with telephones. You can use getMemberContents(...) to retrieve your content based on the conditions you choose as well as a SQL condition. The SQL condition is optional. Steps:
1. Create the condition using the table, the column that labels the field to compare, the operator to use in the comparison, and the value to which to compare the field. 2. Retrieve the Type ID using the known content type. 3. Retrieve list of Content using the condition and the Type ID. public static List contentInCategoryByCondition(Category cat, String table, String column, SQLOperator op, DataValue value, String typename) { List lst = null; try { // Build the condition SQLCondition cond = SQLConditionFactory.buildCondition(table, column, op, value); // Retrieve the Content Type ID int typeId = DataManager.getContentTypeId(typename); // Look in Category for Contents matching Condition lst = cat.getMemberContents(null, cond, typeId, false); } catch (DataException de) { // Unexpected exceptions should get logged. de.printStackTrace(); } return lst; }
90
BroadVision, Inc.
Chap te r 6 Exampl es Workin g with Categori es
Add Members to a Category As your application grows, you may want to add content to the categories you have. (Refer to “Categories” on page 27.) For example, you may want to add more content to the Equipment category. To add members to an existing category, you use DataManager to get the content information before adding the members to your category. Steps:
1. Retrieve the category key for content to add. 2. Retrieve the category using DataManager. 3. Add member content using OIDs to that category. try { ContentKey NodeKey = getContentKey(key); Category cat = myDataManager.getCategory(NodeKey); int memberTypeId = 0; long[] memberOids = getMemberOids(oids); cat.addMembers(memberTypeId, memberOids); } catch (DataException de) { log(“addMembers failed with exception=”+ de.getMessage()); }
Content Guide
91
Ch apter 6 Exa m ples W orking with Categ ories
Create Child Category If a category needs to be logically broken out into smaller segments, you can create child categories. For example, you may want to create a child category within Phones named Smart Phones using the createChild method in Category. Steps:
1. Create child category named “Smart Phones.” 2. Create RowData for the child category. try { String childName = “Smart Phones”; RowData newChildData = new RowData(); newChildData.setValue(...); ... myCategory.createChild(childName, newChildData); } catch (DataException e) { log(“createChild failed with exception=”+ e.getMessage()) res = “DataException”; }
92
BroadVision, Inc.
A
Working with Content Types and Schema Files
This appendix describes in detail the ways in which you can work with content types, create content types, and use the content schema files. This appendix contains the following topics: • “Configuring Content Types,” next • “Extending Content Types and Profile Tables” on page 95 • “Configuring the Display Title for Content Items” on page 110 • “Configuring Content for Browsing” on page 111
Content Guide
93
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Co nfi gurin g Conten t Typ es
Configuring Content Types To configure the content types that appear in the BroadVision Management Center when managing programs, you use the bv.portal.tool.content.PROGRAM_CONTENT_TYPES parameter in the install_dir/baseSuites/bv_services/modules/svc_clt/bv-param.xml file. Use bvtool set-param to update the parameter. For example: bvtool set-param -name bv.portal.tool.content.PROGRAM_CONTENT_TYPES -value content-type1,content-type2
By default, this is set as follows: list of content type names applicable when creating Program stringADEDITORIALPRODUCTSSP_PROCESSURL
After running bvtool set-param, enter the following command: bvtool deploy-config -no-res
The utility prompts to enter yes or no. Enter yes to make sure the application is running and execute bvtool flush-cache DataManager to flush the cache. Enter no to restart the server to make changes appear on the screen.
94
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
Extending Content Types and Profile Tables This section explains how to add new attributes and list tables to existing content types, add new content types, and add or extend the profile tables. The chapter contains the following topics: • “About Content Types and Profile Tables,” next • “Adding a New Content Type” on page 96 • “Adding Attributes to an Existing Content Type” on page 101 • “Modifying the Database Schema” on page 103 • “Displaying New Profile Attributes” on page 107 • “Replacing a Content or Profile Table” on page 109
About Content Types and Profile Tables The Portal content database stores content items according to types, such as product, editorial or advertisement. Each content type specifies a set of attributes for describing documents of that type. If your organization requires different attributes to describe a given type of content, you can extend the content type by adding attributes or list tables (multi-value tables). A content type has one main table and may also have multiple list tables. You can also create new content types. IMPORTANT: You cannot remove or modify any existing attributes or list tables of Portal content
types or user profile tables. User profile data is stored in several tables including several list tables. You can add attributes to any of the tables and add new tables. LDAP Integration: If you configured Portal to integrate profile data with an LDAP repository, the steps for modifying the schema are different. Follow the instructions in the Portal Installation Guide for extending the user profile schema.
Content Guide
95
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
Adding a New Content Type To add a new content type, you modify the database schema and update some configuration files. If needed, you can create a custom detail page (a JSP) for displaying items of the new type. To add a new content type
1. Add the new content type to the database schema. See “Modifying the Database Schema” on page 103 for details. 2. Modify bv-param.xml to specify the display name for the type. You can also enable support for related items and attachments. a. Make a copy of install_dir/baseSuites/bv_services/modules/svc_clt/bv-param.xml and save it to another directory. b. Open install_dir/baseSuites/bv_services/modules/svc_clt/bv-param.xml in a text editor. c. Add a tag to the KEYS parameter definition in the services.content context. The tag should contain the content type name, followed by a colon, followed by the column to use as the display name (or friendly name) when displaying items of that type. For most content types, the display column is the same as the key. You can specify only one column as the display column, even if the content type has a compound key. stringAD:AD_NAMEEDITORIAL:ED_NAMEPRODUCT:PROD_IDURL:NAMEMY_NEW_CONTENT_TYPE:DISPLAY_NAME
d. To enable the content type to have related items, add a tag with the content type name to the RELATABLE_CONTENT_TYPES parameter definition in the services.relatedItem context. .... stringCS_MEETINGCS_TASKDF_MESSAGEPRODUCTEDITORIALMY_NEW_CONTENT_TYPE
96
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
e. To enable the content type to be a related item, add a tag with the content type name to the RELATED_ITEM_CONTENT_TYPES parameter definition in the services.relatedItem context. .... stringCS_MDOCDF_MESSAGEPRODUCTEDITORIALURLMY_NEW_CONTENT_TYPE
f. To enable the content type to have attachments, add a tag with the content type name and corresponding attachment list table name to the ATTACHABLE_CONTENT_TYPES parameter definition in the services.attachment context. stringEDITORIAL:BV_EP_EDATPRODUCT:BV_EP_PDATMY_NEW_CONTENT_TYPE:BV_EP_EDAT
g. Save your changes to the file. h. If you are using the Commerce Services add-on, there is an additional bv-param.xml file to edit. It is located in install_dir/baseSuites/commerce/modules/svc_clt. i. After running bvtool set-param, enter the following command: bvtool deploy-config -no-res
j. Restart your application server.
Content Guide
97
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
3. Create a new content detail JSP and tile, if needed. The default detail JSP for content items, ep/content/default.jsp, provides a generic display page for content items. If the default page is acceptable for your new content item, skip to Step 4. The ep/content directory also contains detail pages for other content types, such as product, editorial, and related items. See those files for examples of detail pages for different content types. To create a new content detail page, copy ep/content/default.jsp to a new name and modify the new file. Store the file in the ep/content directory. Each of the content detail pages accesses the content item through the Content object referenced by the ContentDTO object. (See “ContentViewAction” on page 57 for details on the ContentDTO object.) The following code stores Content to an object called contentMap.
The JSP can then access attributes of the content type through contentMap as follows: // access the DISPLAY_NAME attribute // access the AUTHOR attribute
Next, define a new tile in tiles-defs.xml that references your content detail JSP. The tile should extend .ep.display.page, a layout template for displaying channels, programs, and content items. (For details, see “.ep.display.page Layout Template” on page 27) In the tile definition, set the body attribute to your content detail JSP.
4. Add a new tag to the /ep/contentView action definition in struts-config.xml. The /ep/contentView action calls ContentViewAction to display a content item. If the visitor accesses the content item through a shortcut or alert, ContentViewAction returns the content type name as the ActionForward. (See “ContentViewAction” on page 57 for details.) To handle this case, you need to add a tag with the name of your new content type. The path should be the tile you created in Step 3. If you did not create a custom display page and tile, specify .ep.default.contentView as the path. ....
98
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
5. Create and deploy process models for working with the new content type. The BroadVision Management Center and the foundation application use process models for creating, viewing, editing, and deleting content items. To support these features for your new content type, create the corresponding process models. The PortalPublish and ProductPublish process packs include several process models for working with the built-in content types. Use these process models as a guide for creating your own. See Step 3 on page 101 for a list of the process models for each content item. One process model, called Generic BV Content Delete, handles deleting content items of any content type. You do not have to modify this process model. See the Process Services Designer Guide and Developer Guide for details on creating and deploying the processes. After you deploy the processes, the administrator must map each one to its corresponding content type. See the Administrator Guide for details on process mapping.
Content Guide
99
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
Making New Content Types Searchable If you want your new content type to be searchable, you must perform additional steps. To make your new content type searchable in Portal, you add a new catalog to the searchConfig.xml file using the following steps. For additional details, see the BroadVision Search Adaptors Guide. 1. Edit the searchConfig.xml configuration file. This file is located in config_dir/appConfig/bv_framework/search/. For example:
2. Configure the “name” attribute field as a display name column and add a new attribute field “keyname” as original keyname column. NOTE: If the value of the display name in the old database is empty or null the original keyname
value is used instead of the display name column value. For example to use the column="EP_ABSTRACT" as the display name in the Editorial table, set the name attribute to the EP_ABSTRACT column:
Then, add a new attribute “keyname”; column is original key column:
3. Restart your application server. 4. Index again for the new configuration to take effect. install_dir\lib>bvant.cmd -f ../lib/build-search-collections.xml
100
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
Adding Attributes to an Existing Content Type To add attributes to an existing content type, follow these steps: 1. Add the new attributes to the database schema. See “Modifying the Database Schema” on page 103 for details. 2. Modify the content detail JSP for the content type. The ep/content directory contains the detail pages for content types, such as product, editorial, and related items. Each of the content detail pages accesses the content item through the Content object referenced by the ContentDTO object. (See “ContentViewAction” on page 57 for details on the ContentDTO object.) The following code stores Content to an object called contentMap:
The JSP accesses attributes of the content type through contentMap as follows: // access the DISPLAY_NAME attribute // access the AUTHOR attribute Microsite Content Types
If the content type is a microsite content type, such as task, meeting, announcement, or checklist, you need to modify the corresponding edit and view pages. The edit and view JSPs are located in directories under the cs/microsite directory organized by functional area. The body of the page displays the attributes for the type. The body pages are typically named content_typeEditBody.jsp and content_typeViewBody.jsp. The body of the edit page for meetings is cs/microsite/meeting/meetingEditBody.jsp; the body of the view page is cs/microsite/meeting/meetingViewBody.jsp. 3. Update and redeploy the process models for working with the content type you modified. The BroadVision Management Center and the foundation application use process models for creating, viewing, editing, and deleting content items. You must update the process models that correspond to the content type you modified with the new attributes. The PortalPublish and ProductPublish process packs include several process models for working with the built-in content types. For each content type, one process model handles
Content Guide
101
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
create and update operations, another handles viewing, and another handles viewing revisions in the change history. NOTE: Content types can be enabled for change history when the Content Services extension is authorized in your system. For more information, see the Content Services Guide.
One process model, called Generic BV Content Delete, handles deleting content items of any content type. You do not have to modify this process model. Process pack
Process model
Content type
Used in
PortalPublish
CreateUpdateAD
Advertisement
BVMC, foundation application
ViewAD
Advertisement
BVMC
ViewADVersion
Advertisement
BVMC
CreateUpdateEditorial
Editorial
BVMC, foundation application
ViewEditorial
Editorial
BVMC
ViewEditorialVersion
Editorial
BVMC
CreateUpdateURL
URL
BVMC, foundation application
ProductPublish
ViewURL
URL
BVMC
ViewURLVersion
URL
BVMC
CreateEditProduct
Product
BVMC, foundation application
ViewProduct
Product
BVMC
ViewProductVersion
Product
BVMC
See the Process Services Designer Guide and Developer Guide for details on creating and redeploying the processes. After you redeploy the processes, the administrator must map each one to its corresponding content type. See the Administrator Guide for details on process mapping.
102
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
Modifying the Database Schema If you add a new content type or profile table, or add attributes to an existing content type or profile table, you must modify the Portal database schema. Portal provides a utility, SchemaGenerator, that reads a schema XML file and creates a SQL script to update the Portal database tables. For instance, to add attributes to a content type table, you first edit the appropriate schema XML file, then run SchemaGenerator. The utility generates the SQL script for your database. You then run the SQL script following the instructions provided by your database vendor. NOTE: If you configured Portal to integrate profile data with an LDAP repository, do not use
SchemaGenerator. Instead, follow the instructions in the Installation Guide for extending the user profile schema.
Schema XML Files The schema XML files are located in the install_dir/setup/install/srcxml.locale directory. Some of the most common schema XML files you might want to modify are: • prod_spec.xml—Products content type. • edit_spec.xml—Editorials content type. • adv_spec.xml—Advertisements content type. • prof_spec.xml—User profile tables. Adding an Attribute To add an attribute to an existing content type or profile, open the XML schema file in a text editor to a Content Type and insert a new tag within the tag. or Profile
When you are finished editing the XML schema file, run the SchemaGenerator utility to generate a SQL file. Then run the SQL script following the instructions provided by your database vendor. The tag supports the following tags:
The name of the attribute. This must match the name of the database column.
The attribute’s data type. Specify one of the basic primitive types, or a custom data type that is already known to the system. The valid values are: DATETIME, DBTEXT, DICT, DOUBLE, ENUM, LONG, MONEY, OID, STRING, TEXT See the table below for the data type mappings for your database. The column size for STRING attributes is usually specified with the tag.
Content Guide
Optional. Indicates that the column’s value cannot be null.
103
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
Specifies the following optional properties of the attribute: Indicates that the attribute is part of a primary key or unique index. These properties may occur in XML schema files for existing Portal attributes but should not be used for new attributes you create: , , ,
Specifies a custom value for the column type. Use this tag to modify the default for the data type shown in the table below. For instance, if a STRING column has default size of varchar(255), you can specify varchar(80). For a DOUBLE column, you could specify numeric(18,4).
The friendly name for the attribute.
A description of the attribute.
The following table shows the mapping between the primitive types specified with the tag and the data types in each supported database. Type
Oracle
DATETIME Date
Hsqldb
MySql
DB2
INFORMIX
SQLSERVER
timestamp
Timestamp
Timestamp
Datetime year to second
Datetime
DBTEXT
CLOB
longvarchar
longtext
Longvarchar
Text
Text
DICT
int
int
int
integer
Int
Int
DOUBLE
float
float
Float
Float
Float
Float
ENUM
int
int
Int
Integer
Int
Int
LONG
int
int
Int
Integer
Int
Int
MONEY
numeric(18,2)
Numeric(18,2)
Numeric(18,2)
Numeric(18,2)
Numeric(18,2)
Numeric(18,2)
OID
int
int
Int
Integer
Int
Int
STRING
Varchar
Varchar
Varchar
Varchar
Varchar
Varchar
TEXT
Varchar2(2000)
Varchar(2000)
text
Varchar(2000)
lvarchar(2000)
Varchar(2000)
Adding a New Content Type
104
To add a new content type, create a new XML schema file. When you are finished creating the XML schema file, run the SchemaGenerator utility to generate a SQL file. Then run the SQL script following the instructions provided by your database vendor.
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
The main tag for the file is . Here is the basic structure of an XML schema file for a content type: schemaNameserviceNamecontentTypeIdcontentTypeNamefriendlyName …
The tag supports these tags:
The schema name. This name is stored in the BV_SCHEMA_MAP table.
The service name. Specify ALL_STORE to indicate that the content type applies to all services.
The content type ID. Specify a value greater than 1000. This value must be unique within your Portal installation. No two content types can have the same ID.
The name of the content type.
The friendly name of the content type.
The specification for the table associated with the content type. The supported tags are listed below.
NOTE: Some of the XML schema files for existing content types may contain a
tag. This tag should not be used in XML schema files for new content types you create. The tag contains these main tags: •
—Defines the main content table for the content type. The file must contain only one
tag. • —Optionally defines a related list table (a multi-value table) of the main table. The file can contain zero or more tags. Within the
and tags, use these tags to define the table name and attributes:
Content Guide
The table name.
The friendly name of the table. Use this tag only within the tag. It is required within the tag.
The specification for an attribute/column. Create one of these tags for each attribute. See “Adding an Attribute to a Content Type or Profile” on page 103 for details on this tag.
105
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es NOTE: Some of the XML schema files for existing content types may contain a tag within the
tag. This tag must be used in XML schema files for new content types you create, even if it is empty.
Adding a New Profile Table
To add a new profile table, open the prof_spec.xml file in a text editor and insert a new
tag within the tag. Follow the same format as the
tag for profile tables in this file. When you are finished editing the XML schema file, run the SchemaGenerator utility to generate a SQL file. Then run the SQL script following the instructions provided by your database vendor.
SchemaGenerator Utility To run SchemaGenerator, use the bvtool utility. See the Installation Guide for details on the bvtool utility. First, set BroadVision environment variables by executing, or sourcing, the install_dir/bin/setEnv utility for your operating system. Then execute bvtool with the following syntax: bvtool generate-schema -schema xmlFile -script sqlFile -vendor dbVendor [-noextension]
or bvtool generate-schema -propFile propertiesFile -vendor dbVendor [-noextension]
-schema xmlFile
The name of the schema XML file to use as input.
-script sqlFile
The name of the SQL file to generate.
-vendor dbVendor
The name of your database vendor: oracle, microsoft, mysql, informix, db2, hsqldb
-noextension
Generates the SQL for an entire content type or profile. Use this option when creating new content types or profile tables. No not use this option when adding attributes to an existing content type or profile table.
-propFile propertiesFile A properties file with entries formatted as follows: xmlFilePath=sqlFilePath
Use this option to generate SQL files for multiple XML schemas at one time. See spec_list1.properties in the install_dir/setup/bvf directory for an example of a properties file. This example creates an SQL script for adding attributes to the Editorial content type for an Oracle database: bvtool generate-schema -schema edit_spec.xml -script edit_spec.sql
-vendor oracle 106
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
This example creates an SQL script for a new content type for an Informix database: bvtool generate-schema -schema my_custom_type.xml
Displaying New Profile Attributes If you extend the profile attributes, you need to take a couple steps for the new attributes to appear on the profile page in the portal application and the BroadVision Management Center. To display extended profile attributes in the portal application
1. Extend the profile attributes as described earlier in this chapter. After modifying the schema XML file, be sure to run bvtool to generate the SQL and apply the SQL. 2. Update the profileForm bean in portal.war\WEB-INF\form-beans.xml by inserting a new property for the new profile attribute. For example, if you added an attribute for a cell phone number of type string, insert the following property:
The property name must exactly match the name of the database column that you added. Add this property in the list near the other phone number attribute. 3. Update the portal.war\ep\common\changeProfile.jsp file with the new attribute. For example:
Cell phone:
To display extended profile attributes in the BroadVision Management Center
1. Extend the profile attributes as described earlier in this chapter. After modifying the schema XML file, run bvtool to generate the SQL and apply the SQL.
Content Guide
107
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Extendi ng Con te nt T y pes and Profile T abl es
2. Update the mtUserEditForm bean in bvmc.war\WEB-INF\conf\form-beans-mt.xml by inserting a new property for the new profile attribute. For example, if you added an attribute for a cell phone number of type string, insert the following property:
The property name must exactly match the name of the database column that you added. Add this property in the list near the other phone number attribute. 3. Update the mtUserView view bean in bvmc.war\WEB-INF\conf\view-beans-mt.xml by inserting a new property for the new profile attribute. For example:
The property name must exactly match the name of the database column that you added. Add this property in the list near the other phone number attribute. 4. Update the bvmc.war\mt\user\userViewBody.jsp file with the new attribute. For example:
Cell phone:
5. Update the bvmc.war\mt\user\userEditBody.jsp file with the new attribute. For example:
Cell phone:
108
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Extendi ng Con ten t T yp es and Profile T abl es
Replacing a Content or Profile Table If you need to redefine the schema of a content or profile table, recreate the table. To redefine the schema of a content or profile table
1. Edit the .xml schema file. 2. Regenerate the SQL file for the complete table using generate-schema (SchemaGenerator) with the -noextension flag. Refer to “generate-schema (SchemaGenerator)” on page 46. 3. To retain data from the existing table, save it into a temporary table (or export the data). This action allows you to reinsert the data into the new table later. 4. Apply the generated SQL file. IMPORTANT: Applying the generated SQL file removes all existing data in the table. Refer to Step 3.
5. Reinsert any data saved from the original table.
Content Guide
109
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Co nfi gurin g th e Displa y T itle fo r Co ntent Items
Configuring the Display Title for Content Items NOTE: This is an abbreviated version of the information in “Adding a New Content Type” on page 96.
Content items require that the content title for each content item be unique. This is because the content title is the unique key column in the content table. When you have many content items, it can be difficult to make each content title unique. You can now choose any other column in the content table to be the display name for content items. However, this change is limited to the Portal application. Content items in the BroadVision Management Center still display the content key as the content title. To configure the column to use as the display name for content items
1. Edit the bv-param.xml configuration file. This file is located in install_dir/baseSuites/bv_services/modules/svc_clt/. 2. Find the section of the file. 3. Specify an attribute for each content type that will hold the display name of the content item. For example, to make the author column the display name for the editorial content type: Mapping of content display name key stringEDITORIAL:AUTHOR
4. Save your changes to the file. 5. If you are using the Commerce Services add-on, there is an additional bv-param.xml file to edit. It is located in install_dir/baseSuites/commerce/modules/svc_clt. 6. After running bvtool set-param, enter the following command: bvtool deploy-config -no-res
7. Edit the searchConfig.xml configuration file. This file is located in config_dir/appConfig/bv_framework/search/.
110
BroadVision, Inc.
Ap pen dix A
W orking wi th Co ntent T y pes an d Sch ema Fil es Config uring Co ntent for Browsin g
Configuring Content for Browsing You could have hundreds of content types available, however you may only need to display a dozen or so for browsing purposes. You can use the bvtool utility interactively to enable and disable content for browsing. When you use the tool interactively, you provide values when prompted. To enable or disable content for browsing
1. Determine which content types are enabled for browsing. a. From the command line, run bvtool get-param. b. Enter the parameter bv.core.content.BROWSABLE_CONTENT_TYPES. A list of content types currently enabled for browsing is displayed; they are listed by their Friendly Name attributes. 2. Add the content type you want to the list of content types enabled for browsing. a. From the command line, run bvtool set-param. b. Enter the parameter bv.core.content.BROWSABLE_CONTENT_TYPES. c. Enter the friendly names of the content types currently enabled for browsing, and include the friendly name of the content type you want to browse. Separate names with commas and spaces, as the next example shows: AD, EDITORIAL, PRODUCT 3. Deploy the change to the configuration: a. From the command line, run bvtool deploy-config -no-res. b. Respond “No” when prompted to notify the running applications.
Content Guide
111
App endi x A Wo rki ng with Con te nt T y pes and Sche ma F ile s Co nfi gurin g Conten t for Brow si ng
112
BroadVision, Inc.
B
bv-updater
The bv-updater utility imports, updates, and deletes content information or category information into your BroadVision content database. The utility processes data contained in XML files. IMPORTANT: This utility works on information in internal content database tables only. You cannot use this utility to import information into externally defined content database tables or into the versioned content store that BroadVision Content Services provides.
App endi x B bv-upd ater Co nfi guratio n Fil e for bv-up dater
Configuration File for bv-updater The configuration file for bv-updater utility is a text file that contains the following parameter definitions. Parameter and value
Meaning
noval=y
Turn off XML validation. Omit this parameter to perform validation.
log=logFilename
The file to receive log messages. The file is written always in the current directory. The default name is bv_updater.log. Use this parameter to specify a different name. The log file reports the count of rows updated. If an error occurred, it reports the line in the XML data file that was erroneous. NOTE: On Windows, use double backslashes (\\) in the path if you provide one. For example,
log=c:\\logs\\bv_updater.log IMPORTANT: A new log file is written each time you run the bv-
updater utility. The log file is not cumulative. onetran=y
Process the input file as one database transaction. Omit this parameter to process each database action (such as insert or update) as a discrete transaction.
partial_commit=y
Allow database operations within a single commit scope to continue If errors occur while processing records. Omit this parameter to roll back a commit scope on the first record failure. NOTE: This parameter has no effect on the MOVE_CATEGORY operation.
lc_number=langCode_countryCode
(Optional) Locale to use when parsing numbers from the input file. Default is the locale of the server. See the Installation Guide for common codes.
lc_datetime=langCode_countryCode (Optional) Locale to use when parsing date-time values from the input file. Default is the locale of the server.
You can find a sample bv_updater.cfg file in this location: On UNIX
install_dir/baseSuites/bvupdater/samples On Windows
install_dir\baseSuites\bvupdater\samples
114
BroadVision, Inc.
App endi x B bv-upd ater De pend encie s of bv-upd ater
Dependencies of bv-updater The bv_updater utility has these dependencies: • “A Running BroadVision System,” next • “Environment Settings in the Operating System” on page 115 • “File Locations of the DTDs” on page 116
A Running BroadVision System Your BroadVision system must be running before you can use the bv-updater utility. You run the system by starting the servers. See the Installation Guide for instructions on how to start the servers on your operating system platform.
Environment Settings in the Operating System The bv-updater utility depends on the environment variables to be set correctly. Issue the following command before you run bv-updater: On UNIX
. install_dir/bin/setEnv.sh On Windows
install_dir\bin\setEnv
Content Guide
115
App endi x B bv-upd ater De pend encie s o f bv-upd ater
File Locations of the DTDs In order for the bv-updater utility to validate the format of your data files, you must specify the locations of the Document Type Definitions (DTDs) for content data files and category data files. The files are bvupdater.dtd and bvupdater_category.dtd, which you find in this directory after you install the software: install_dir/baseSuites/bvupdater/samples
Specify the locations in one of these ways: • Copy the DTDs to the directory that contains your bv-updater configuration file. • Specify the full paths and filenames of the DTDs in your data files. For content data files
For category data files
116
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
Input File Formats for bv-updater The bv-updater utility works with two formats of input files: • “Content Input Files,” next • “Category Input Files” on page 123 When you run bv-updater, it processes either a content input file or a category input file.
Content Input Files The information in a content input file has these restrictions: • The information is for content in a specific service. • The information is for a specific Content Type, including the main content table and any multivalue attribute tables. Content input files have this general XML structure: Defines the service and the content type
Defines the attributes and rows of data for one of four actions: Insert, Update, Replace, or Delete
Defines the attributes that the data rows contain for the specified action
Defines the data rows to process for the specified action Attributes follow the order defined in the action specification valuevalue …
You can find examples of content input files in this location: install_dir/baseSuites/bvupdater/samples
Content Guide
117
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
Locales
IMPORTANT: If your BroadVision Portal application uses a non-English character set, use the same
character set to prepare your data input file. Errors can occur if you use a non-matching character set. For non-U.S. English locales, specify the character set of the language in the XML header. The next example shows how to identify the character set to import Japanese strings:
The and elements in the section identify the service and the content type for the content input file. The next example shows how: C3PRODUCT
There are four content database actions that you can specify in a content input file: • insert new rows into the table • update existing rows with new information • replaces existing rows, and inserts new rows • removes rows Each file can have multiple actions, and the actions may be different — you can mix the actions, such as including both insert and delete actions in the same file. A content table can have more than one column as the key, for example, BV_POLICY has 4 columns together as a unique key comprising: NAME, VERSION, PACKAGE_NAME, POLICY_TYPE. To use bv-updater with a multi-column key, you need to specify all column names of the key in the XML file for bv-updater, for example, for UPDATE action: .... bv-updater supports multi-column keys in UPDATE, DELETE, and REPLACE for a main content
table, and INSERT, UPDATE, DELETE, and REPLACE for a list content table.
118
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
Inserts new rows. For main tables, at least one attribute must be the key field for dependent rows in related multivalue attribute tables. Omitting an attribute inserts a null into the new column. PRICE …
To insert rows into a multivalue attribute table, use the element to identify the name of the table. Also, the first attribute must be either the key field or OID of the main content table. BV_PROD_TRANSLATE …
For the specifications above, the first in the is the OID in the main table. If the OID is not found in the main table, the insert fails. 50002telephone IMPORTANT: Attachment files are not inserted by bv-updater. Only references to their locations in
the file system are inserted.
Updates existing rows with new information. The specifications are the same as for . Unlike , you must explicitly enter every column data in each row, and the OID cannot be updated. …
Content Guide
119
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
To update multivalue attribute tables by key field, identify the table name with the element, and the key field in the main table with the element: BV_PROD_TRANSLATE …
Similarly, to update by OID instead of key field, specify “OID” in the key name: BV_PROD_TRANSLATE … is a column in the multivalue attribute table that identifies rows to update. For example, the BV_PROD_TRANSLATE table is related to the BV_PRODUCT main table by the OID . The LANGUAGE identifies individual dependent rows of the main product row: 500022German …
120
Replaces existing rows in main tables and multivalue attribute tables and inserts new rows in main tables only. In the main table, if the key or OID value in the is found in the table, that row is updated; otherwise, the data is new and a new row is inserted in the main table.
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
For replacements in a main table, use a element: … …
For replacements in a multivalue attribute table, use the elements to identify the attributes in the target table: BV_PROD_TRANSLATE … …
Note that you can include and elements within the , for example: … … … …
For a replacement in a multivalue attribute table, if there is no value in the for attribute value, the row is inserted into the table. Otherwise, all of the rows in the list table that match the value are deleted, and then the new row is inserted.
Content Guide
121
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
For example, the following element contains two rows to insert. The first row identifies 50004 as the attribute value, and as such, causes the deletion of all exiting rows that depend on the 50004 main row. After the existing rows are deleted, two new rows are inserted into the multivalue attribute table: BV_PROD_TRANSLATE … 5000450112…50112…
Removes rows from the table. The lists either an OID or key field, and the lists the ID values of the rows to delete. Note that invalid keys (ones not found in the table) are ignored:
To delete rows from multivalue attribute table, identify the table, and the key or OID in the main table: BV_PROD_TRANSLATE IMPORTANT: Content is physically deleted from the underlying relational database. In versions of
BroadVision applications prior to 8.0, content could be marked for deletion with the DELETE column in the main table instead of being deleted physically. Beginning with the 8.0 versions of BroadVision applications, the DELETE columns in main tables are not used and the bv_purge_on_delete system parameter is not available.
The section contains the rows of data to either put in, or remove from the content type. Each element contains the values for one row in the database. Within each row, the elements contain the data values, and the order of the values correspond to the order of attributes identified in the element. 122
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
Here are several alternatives for specifying attribute values: value value
If there are fewer definitions than attributes were defined in the element, the remaining attributes are treated as null.
Category Input Files The information in a category input file is for a specific service within a BroadVision system. You can combine actions for categories of different content types in one category input file. Each category XML input file has this general format. Defines the content type, the category attributes, and the rows of category data for a category action
Defines the attributes that the data rows contain for the specified action
Defines the data rows to process for the specified action Attributes follow the order defined in the action specification valuevalue … Important: Category input files have a limitation of 5000 categories. If you have more than 5000 categories to insert or update, use multiple files.
Content Guide
123
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
You can find examples of category input files in this location: On UNIX
install_dir/baseSuites/bvupdater/samples On Windows
install_dir\baseSuites\bvupdater\samples Locales
For non-U.S. English locales, identify the character set of the language in the XML header. The next example shows how to identify the character set for importing Japanese strings:
The element in the section identifies the service for the category input file. The next example shows how: C3
The element in the section identifies the content type for user category input files. Use this element only for input files that contain user categories. The next example shows how: C3USER_CATEGORY
There are eight category database actions • — insert new category rows • — update existing category rows with new information • — replaces existing category rows, and inserts new rows • > — moves a category from one parent category to another • > — removes category rows • — renames category node names • — sets category online/offline status • — added content references to categories • — removes content references from categories
124
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
Creates new categories. The element identifies the content type that the new categories belong to. The insert action creates all of the required attributes, such as creation time, and parent OID. You should specify the status as either or (the default). Note that you cannot turn on the status of a subcategory when the parent category is offline: PRODUCT
/Toys//Toys/Dolls/Toys/Board Games
The in identifies the category to create. To create a category path, include a for each category that does not already exist. The example above creates the root category “Toys” before creating the two subcategories “Dolls” and “Board Games.”
Modifies category attributes in existing rows. In the , the element identifies the content type of the category, and the elements identify the category attributes to receive the updated information: PRODUCT … /Toys… … NOTE: You may not update the path name and online/offline status attributes. To change the path, use . To change the status, use .
Content Guide
125
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
To update multivalue category attributes, use to identify the multivalue attribute table, and element to identify the key fields in the table. For example: PRODUCTBV_CATEGORY_TRANSLATE
Replaces existing rows in the category main table and multivalue attribute tables and inserts new rows in the category main table only. For replace/updates, you may not change the path name and online/offline status attributes: use and for that. For inserts, you should specify the status as either or (the default).
Note that you cannot turn on the status of a subcategory when the parent category is offline. You can combine updates to the main and multivalue attribute tables in one input file with the and elements: … … … …
Moves categories from one parent category to another. Use the element to specify the category you want to move. Use the element to specify the new parent after the category is moved. The following example moves the Computer Games category from its current parent, /Toys/Games, to its new parent, /Computers/Entertainment: PRODUCT/Toys/Games/Computer Games/Computers/Entertainment/Computer Games
126
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
Removes existing categories. To delete categories, identify the content type (), and the category paths () to remove: PRODUCT/Toys/Toys/Dolls/Toys/Board Games
Changes the name of the last category in a category path. Use for the existing name, and for the new name: PRODUCT/Toys/Costumes/Toys/Halloween Costumes
Note that you can only change the category in a path. /Toys/Costumes/Girls --> /Toys/Costumes/Women /Toys/Costumes/Girls --> /Toys/Garments/Girls
<-- OK --> <-- Bad! -->
Sets the status of a category to online or offline with or attributes. If you omit the attribute, the status is set to offline by default. You can change the status of all categories in a content type at the level. The next example turns on all product categories with : PRODUCT
Content Guide
127
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
You set the status of specific categories at the level with : PRODUCT/Toys/Toys/Costumes/Toys/Educational
Turning off a parent category turns off all of its subcategories. You cannot turn on a category when the parent is turned off.
Adds content references to a category. The element specifies the addition action, and the element identifies a reference to add. There are three ways to add references. You can add multiple references within each element; however, only one of the three ways is allowed within each element. Add by OID.
PRODUCT/Toys/Dolls90049003
128
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater Add by content key.
PRODUCT/Toys/Dollskey value1key value8key value7 Add by query condition. Here the element is a query string that adds references to the
/Luxury Items category — references to products whose price is greater than 1079.49: PRODUCT/Luxury Itemsprice > 1079.49
Content Guide
129
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
Removes content references from a category. The element specifies a remove action, and the element identifies a reference to remove. There are three ways to remove references. You can remove multiple references within each element; however, only one of the three ways is allowed within each element. Remove by OID.
PRODUCT
/Toys/Dolls90049003 Remove by content key.
PRODUCT
/Toys/Dollskey value1key value8key value7 Remove by query condition. Here the element is a query string that removes all references from /Toys/Dolls/Inexpensive whose product price is greater than 133.49:
PRODUCT
/Toys/Dolls/Inexpensiveprice > 133.49
130
BroadVision, Inc.
App endi x B bv-upd ater In put F ile F ormats for bv-upd ater
The element identifies • Category path names () to add, change, or remove. • Category attribute values () to add, change, or remove. • Category status flags to set () or turn off (). • Content references () to add or remove from categories. Each element in the element contains the information to record in the database. Within each row, the element identifies the category path. To create a nested path, include a for each path that does not already exist in the category hierarchy. The following example creates the root category “Toys” if it does not already exist. Then it creates the “Board Games” subcategory if it does not exist. The element provides the same value for both categories. /Toys/Toys/Board Games1 …
The order of the values corresponds to the order of attributes identified in the element. If there are fewer definitions than attributes were defined in the database action element, the remaining attributes are treated as null. Here are several alternatives for specifying attribute values: value value
Content Guide
131
App endi x B bv-upd ater Inpu t Fi le Fo rma ts fo r b v-u pdater
132
BroadVision, Inc.
C
Glossary
This appendix contains a list of terms associated with content.
Term
Definition
Attribute
Column in the database.
BV_CATEGORY
Content items of a particular content type are contained in a dedicated content table but categories for all content types are contained within a single table, BV_CATEGORY.
BV_EXT_MAP
The BV_EXT_MAP table identifies the mapping table between external tables and the BroadVision mapping table. The BroadVision mapping table maps attributes to key columns in external tables. This table identifies the external table and the mapping table.
Category
Categories are arbitrary groups of content items that you create within a content type. Properly organized and implemented, categories can greatly enhance the success of your website by helping visitors more easily find the content for which they are looking. Using categories, your website application can display groups of content in direct response to visitors’ inputs.
Category Roles
Category roles let you control access to content categories and content items. Individuals and groups that you add to the member list gain the privileges you permit. You must have the role of Content Administrator to manage category roles.
Column in the Database
Attribute
Compound Key
The content key can be made up of multiple attributes. These attributes can be any combination of attributes from within the table.
Content Item
An individual piece of content. Consists of multiple pieces of information contained in a row in the database. Content items require that the content title for each content item be unique. This is because the content title is the unique key column in the content table.
Content Key
In BroadVision, the content key is that attribute which uniquely identifies a content item. It is typically a friendly name. The name of the content key varies from content type to content type. The type of the content key can be either INTEGER or it can be STRING with a COLUMN width specification of varchar(). Additionally, content key is used to identify or access a category using its pathname.
Content Guide
133
App endi x C Glossary
Term
Definition
Content Type
A content type names a table, names its columns, and defines what kind of data each column can hold. Content types are defined by schema specification files. BroadVision content types range from 1-1000
Content UID
Every content item in the database has a unique Content UID, which consists of three fields: The content type ID, Service ID, OID.
Extended Data Type (*_type.xml)
Based on your DBMS’s primitive types and described in the schema specification files.
external_profile_sc This file is located at install_dir/apps/bpmappsample/data/ldap. hema_ext.xml Used to extend the user profile schema. GUID
An identifier. GUIDs are unique across the content types while OIDs are unique in their context only.
List Table
See Multivalue Attribute Table.
Mapping Table
The BV_EXT_MAP table identifies the mapping table between external tables and the BroadVision mapping table. The BroadVision mapping table maps attributes to key columns in external tables. This table identifies the external table and the mapping table.
Metadata Table
Tables that describe the database. All meta tables can be found in
Some attributes contain a list of values, such as a list of a product’s available colors. Such multivalue attributes are the child tables in one-tomany relationships, where the content table is the parent. Attributes with multiple values are stored in separate database tables, sometimes called related attribute lists. Multivalue attributes behave the same as ordinary single-value attributes in that you can search them and include them in queries. Also referred to as related attributes or list tables.
Object-relational Model
Data stored in the database are treated as objects by programs. When the API retrieves a content item from the database, it packages it as an object.
OID
Besides the content key, all content items have another unique identifier that is automatically assigned by the BroadVision framework called the OID (or Object ID). The BroadVision framework uses the OID to relate various tables together. OIDs are unique in their context. Category OIDs are negative while content OIDs are positive.
Profile Data
Profile data (prof_type.xml) describes visitors and contains registered visitor profile information.
Related Attribute
See Multivalue Attribute.
Rules
Use rule sets to generate content to display in programs. The content a rule set generates is based on the rules that comprise the rule set. Every rule set has an evaluation method and a default action.
134
Schema Specification File (*_spec.xml)
Content types are defined by schema specification files. Each schema specification file contains a set of keyword statements that specify the content type, the table name, the column names, the data types that the columns can hold, and a number of other characteristics.
Service
A service is simply a portion of the database devoted to a particular purpose. For example, the Portal foundation application uses data from the C3 service.
BroadVision, Inc.
Appe ndi x C Glossary
Content Guide
Term
Definition
Service ID
The numerical identification for a service.
Store ID
See Service ID.
Uncategorized Content
Content becomes uncategorized when someone deletes the category that contained the content. You can move uncategorized content into a category in the hierarchy, or you can delete it from the content database.
135
App endi x C Glossary
136
BroadVision, Inc.
Index
A about this book 7 adv_spec.xml 103 API data access packages 54 examples 67 overview 52 using 51 application data tables 37 attribute type adding 46 attributes 18 audience 7
B book organization 7 BroadVision Management Center 44 bulk load external data 39 bvant 49 bv-param.xml 96 bvtool 44 bv-updater 45 setting environment 115 bv-xmldumper 45
C categories 27 cannot span content types 31 XML input file 123 content about 12 uncategorized 30 XML input file 117 content categories
E edit_spec.xml 103 examples 67 extended data types 36 extending content types 95 profile 95 Extending the Content Schema 33 external content 33 external data source 39
M mapping tables 39 Mechanisms for Working with Content 16 meta-data tables 38 microsites content types 101 multivalue tables 19
O OID description 25 referential integrity 25
P G generate_xsd 49 generate-schema SchemaGenerator 46 Generic BV Content Delete 102 glossary 133 GUID description 26
password changing database password 45 PortalPublish process pack 102 prod_spec.xml 103 ProductPublish process pack 102 prof_spec.xml 103 profile extending 95
R I image files 19 inline publishing 44 input file content, XML file 117 input files categories, XML file 123 interface 66
L LDAP 41 list tables 19 load-portal-data 44 LoadUsers 44
138
referential integrity OID 25 related attributes 19
S schema extending 33 modifying 103 schema specification files 23 SchemaGenerator utility 106 service 38 set-db 45 setEnv 115 setting environment for bv-updater 115
BroadVision, Inc.
Index
T tables application data 37 mapping 39 user profile 41 tools and utilities overview 14 type adding 46 Typographical conventions 8 typographical conventions 8
U uncategorized content 30 user profile tables 41
X XML input file content 117 XML input files categories 123
