Ch 14 Specs/Mappings

The Specs/Mappings component of the Data Model Manager provides access to the Specs Console and the Spec Map Console.  


Specifications ("Specs")

The following is a list of spec characteristics:

Specs Console

The Specs Console allows a user to easily navigate and view the following specifications.

Figure 14.1 - Specs Console

Accessing the Specs Console

To access the Specs Console, use the menu path
Data Model Manager > Specs/Mappings > Specs Console.

Navigating the Specs Console

To navigate between different spec types, use the Spec Navigation bar.

Figure 14.2 - Spec navigation bar

The top-level buttons can be clicked to view its associated spec type

To search a spec by name for a specific spec type, select a spec type and a letter from the alphabet selection on the navigation bar. All specs starting with the selected letter appear. Click "All" to view a list of all specs for a selected spec type

Spec Types

File Defines data elements of incoming data
Primary Defines item attributes, category hierarchy attributes, and organizational hierarchy attributes. 

These specs can be attached to catalogs, category hierarchies and organization hierarchies

Lookup Defines lookup table record attributes
Destination Defines data elements at destination
Secondary specs Secondary specs are used as item hierarchy specs or as standalone specs. The secondary specs are attached to categories. 

If a secondary spec is attached as a item hierarchy spec, the attributes will be available to all items under the category. 

If a secondary spec is attached to the category as standalone specs, it will be available only at the category level for a specific category

Script An input spec that defines attributes to be passed to a script (input parameters)

Spec Management

Creating Specs

To create a spec, select a spec type from the Spec toolbar and click the New button located in the spec table heading. Refer to the following sections on creating and defining specs (Attribute Management).

Editing Specs

If desired, a spec can be edited from the Specs Console by clicking on the Edit button . Edit can be made from the spec tree and saved by clicking the Save button at the bottom of the screen.

Add Nodes

When a spec is created, nodes are be added in a treelike structure and parameters are defined for each node, such as the field length and the data type. If needed, additional parameters can be added (i.e. maximum length, required flag, data type, etc.)

Add attributes to a spec

1. To add a node, click the Plus icon on the spec tree.

2. Enter a name for the node and click the Plus icon, located at the end of the entry field. The attribute is added to the Spec Tree and the details box appears. The next step is to define the node parameters.

Figure 14.3 - Adding a node

3. To define node parameters, enter information in the Details table and click Save to commit the change.

Figure 14.4 - Define node parameters

4. To add additional attributes, choose a value from the drop-down selection under the Display Name field, then click the Plus icon. The value is added in the Details box. Enter a value for the attribute and click Save.

5. Enter information into the new attribute field and continue adding nodes and node parameters, as needed.

6. When all of the nodes and node attributes are added, click the Save button at the bottom of the screen to store the spec.

Note: If the Save button is not clicked, the newly created nodes will not appear in the spec.

Edit or delete nodes

Nodes on a spec tree can be edited or deleted at anytime. Be careful when making any changes to a spec as it will change all the objects that are using the spec. For example, if a node is deleted from a primary spec, any catalogs that use the spec will no longer have the node in the catalog along with their values. This action cannot be reversed.

Editing node

To edit an attribute, click on the node name on the spec tree. Make modifications and click the Save button.

Deleting a node

To delete a node, simply find the node in the spec tree structure and click the garbage can icon next to it.


Spec Node parameters

A node parameter can be in any type of spec, a number of parameters may be set for each attribute (node). These parameters define how data is to be calculated, stored and/or validated for that attribute (node).

All specs are created in a tree structure that is built by adding and defining node parameters. This section explains how to add and define spec nodes.

Node parameters

Defining node types are important to create and maintain a standard structure for product information. With multiple users handling the data, a miscue in data entry will produce an error message.

When adding nodes to a spec, they can be defined with the following parameter characteristics:

Data Types Strings, Numbers (Integer, Decimal, Currency), Enumerations (Number, String), Images (Binary), Dates, Flags, URLs, Groupings, etc.

Editable 

An attribute can be made editable or not. If unchecked, the value for this field is viewable and cannot be edited

Unique 

Creates a requirement for the node to be unique in a catalog. If a user attempts to enter a duplicate value, an error occurs. Option only available in Primary specs.

Link 

Defines a node as the "source attribute" or "foreign key" to the master catalog. Option only available in Primary specs.

Hidden 

Defines a node that is not displayed and is useful for nodes that are used as placeholders for intermediate values. When this box is checked, the node is hidden and when unchecked it is displayed. Although this feature hides a node from the item view screens, it is exposed to scripts and searches.

Runtime Searchable Check this box to include the node for runtime searches. If the box is not checked then it is available to background searches. Use this option for common searchable nodes.

Non-Persistent 

Provides the ability to make a node not constant

Localized 

 Set attribute for localization. Company must be set with the desired locales.

Node parameter limitation

There is a limit to the number of characters in a value/validation/string-enumeration rule. It can be at most 3000 bytes, which in most cases translates to 3000 characters (including spaces). It can be less than that depending on the characters used e.g. Japanese characters etc. can be more than one byte long.

Adding scripts

Each node within a spec is associated to a node of any type. Therefore, scripts can be created to perform rules for a node.

Node data types

Each node within a spec is associated with a data type, which controls the following:

The available data types differ between each spec type. This section lists the different data types available in WebSphere Product Center.

Binary

Function: Store binary data, i.e. PDF files, Image files.
Available in Specs: All
Rules associated: None

After an attribute has been defined as Binary, the catalog attribute can be used to upload a binary file into WebSphere Product Center. Click the Edit icon from the Item Edit screen and the Upload Image screen appears.

Currency

Function: Define currency fields. By default, the value is rounded to the second decimal place
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, Validation rule, Value Rule

When adding a value to the attribute, it is rounded to the second decimal point.

Date

Function: Define date fields
Available in Specs: All
Rules associated: Date format, Default value, Minimum length, Validation rule, Value rule

Apply the spec to an object and the date format appears in the format as defined. Select from a set of pre-defined date values or enter a date manually.

Flag

Function: Holds one of two states, true or false
Available in Specs: All
Rules associated: Default value, Validation rule, Value rule

A checkbox is created for selection. An empty box could be searched for as a null value for the node.

Image

Function: Used to store images
Available in Specs: All
Rules associated: None

After a node has been defined as "Image", the catalog attribute can be used to upload an image file into WebSphere Product Center. Click the Edit icon and the Upload Image screen appears.

Image URL

Function: Used to store a URL location of an image. WebSphere Product Center fetches the URL from the defined location
Available in Specs: All
Rules associated: Default value, Minimum length, Patter, Validation rule, Value rule

In the catalog item view, a URL for a graphic can be entered. Click on the Preview button to view the image.

Integer

Function: Used to store only integer numbers. Numbers with decimals are rounded to form an integer.
Available in Specs: All
Rules associated: None

Any of the natural numbers, the negatives of these numbers, or zero must be entered for this attribute. If an integer is not entered for this attribute, an error occurs.

Lookup table

Function: Associate to a lookup table, which provides a drop-down selection of lookup tables that have been created
Available in Specs: All
Rules associated: Value rule

Number

Function: Used to store double numbers, i.e. number which can hold decimal values. (For example, 10.98)
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, Validation rule, Value rule

A number is defined to allow a number value with a decimal value. If no decimal value is given, it given a value of ".0". Negative values are allowed.

Number Enumeration

Function: Used to create a list of number data types. Negative and decimal values are allowed.
Available in Specs: All
Rules associated: Number enumeration rule

1. Set the data type to "Number Enumeration".

2. The details table adds a Number enumeration row. Click the "CLICK HERE" hyperlink and a separate dialog box appears.

3. Add a number in the Spec Enum Details table and click the Plus icon.

4. Continue to add number values to the enumeration and click Close Window when finished.

5. The values entered are displayed in a drop-down selection format and are listed in ascending order.

Password

Function: Refers to an alphanumeric field which hides the contents to the user
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, Validation rule, Value rule

When entering a value, it is displayed with asterisks. This is useful when values are to be hidden.

Period

Function: Creates two Date fields, Start Date and End Date
Available in Specs: All
Rules associated: Default value, Minimum length, Validation rule, Value rule

The GUI creates a field with a Start and End Date value.

Relationship

Function: Used to hold a link to another item in the same or another catalog
Available in Specs: Catalog Spec
Rules associated: Default Value, Validation rule, Value rule

The GUI allows a user to select a catalog and a key attribute to link two catalogs. The Key value allows for a link relationship to be established.

Sequence

Function: Used to create a numbered sequence field
Available in Specs: Catalog, Lookup table, Category, Hierarchy
Rules associated: Default value, Increment sequence by, Default value for sequence start, Minimum length, Validation rule, Value rule

Set a rule associated to the data type, i.e. set the Default value for sequence start at "1". When a new item is added, the sequence field automatically enters "2". This field is not editable to the user.

String

Function: Holds a string or character data
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, Validation rule, Value rule

If desired, create an associated rule for the attribute. The GUI displays an empty field for data entry.

String Enumeration

Function: Create a string enumeration data type that holds a list of string data types
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, String enumeration rule, Validation rule, Value rule

Associate a rule with the data type, which displays all values in a drop-down selection field.

Thumbnail image

Function: Stores a thumbnail image
Available in Specs: All
Rules associated: Default value

A user is able to load a thumbnail image and view it from the GUI.

Thumbnail Image URL

Function: URL link to a thumbnail image. WebSphere Product Center will fetch the image from a defined URL.
Available in Specs: All
Rules associated: Default value, Value rule

The field allows for an address to be entered for the Thumbnail Image URL. Set a Maximum length for the attribute.

URL

Function: Define a URL field and appears as a link on the item list and item detail screens
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, Validation rule, Value rule

The field allows for an address entered for a URL.

Setting node rules

Once a data type is selected, additional rules can be added to further define the characteristics for an attribute.

Default Value

Function: Define a default value for an attribute.
Available in Specs: All

Default value for sequence start

Function: Define a default value for a sequence.
Available in Specs: All
Rules associated: Sequence

Help URL

Function: Define a Help URL; used to customize help.
Available in Specs: All

Although WebSphere Product Center has general help topics available for application assistance, the ability to have an attribute link to a URL can be utilized to create customized help topics.

Increment sequence by

Function: To increment a sequence by a defined value
Available in Specs: All
Rules associated: Sequence

Lookup Table

Function: Defined an associated lookup table. No value is available if no lookup tables exist.
Available in Specs: All
Rules associated: Lookup Table

Minimum Length

By default, the Maximum Length is provided. To set the node to a minimum length is must be defined explicitly from the attributes details screen.

1. A minimum length can be defined by selecting "Minimum Length" and click the Plus button.

2. Enter a value in the Minimum Length field.

3. Click save to update the spec.

Number Enumeration

Function: To defined a enumerated number attribute:

1. Select Number Enumeration Rule and click +, the Number Ennumeration field appears.

2. Click "CLICK HERE" to access the pop up window used to create a number enumeration..

3. After creating a number enumeration, click Close.

Occurrences To Display

Function: To defined the number of occurrences that are displayed, if an attribute is defined as multi-occurrence:

1. Select the Occurrences To Display Rule and click +.

2. Enter a value in the Occurrences To Display field.

Pattern (regular expression)

To defined an attribute with a pattern for a regular expression.

1. Select the Pattern (regular expression) Rule and click +.

2. Enter a pattern for a regular expression.

String Enumeration

Function: Create a string enumeration data type that holds a list of string data types
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, String enumeration rule, Validation rule, Value rule

1. Set the data type to "String Enumeration".

2. Click "CLICK HERE" for a pop up window used to create a string enumeration

String Enumeration Rule

Function: Create a string enumeration rule for data type that holds a list of string data types
Available in Specs: All
Rules associated: Default value, Minimum length, Pattern, String enumeration rule, Validation rule, Value rule

1. Set the data type to "String Enumeration Rule".

2. Click "CLICK HERE" for a pop up window used create a string enumeration rule.

Validation Rules

Function: To defined a validation rule for a node.

1. Select Validation Rule and click +, the Validation Rule field appears.

2. Click "CLICK HERE" to access the Validation Rule Editor.

3. Create a Validation Rule for the attribute and click Save.

Value Rule

Function: Create a value rule for the node

Grouped nodes

Nodes can be grouped on any spec tree. When grouping nodes, it is important to create all major groupings before adding sub-nodes to each group. Use the Single Edit screen to view grouped nodes as the multi-edit screen will not appear in the Multiple Edit screen.

Creating grouped nodes

Figure 14.5 - Grouped nodes

The following steps create an example of grouped nodes.

1. When creating a spec, click the root node and add the first level group node (i.e. Group A).

2. Click the "Group A" attribute to add a sub-node, "Group A1"

3. Click the "Group A1" node to add a sub- attribute, "Group A1-1". The spec tree appears with three group levels.

4. Add a node under any of the grouped nodes. Before adding sub-nodes, all parent level groupings must be created before adding sub-nodes.

Note: When grouped nodes have been created, use the Single Edit screen to display groups as they do not appear in the Multiple Edit screen.


File Specs

A file spec is created to define the file structure of an external data source. The file spec is needed for the importation of a source file into WebSphere Product Center. Analyze the structure of the data source and create a file spec that emulates the structure.

If the data source changes at a later time, the file spec can always be modified to reflect the changes.

Creating a File Spec

1. Select Spec Type

By default, File Spec displays in this step.

2. Enter File Spec Name

Enter a unique name for the new file specification. Choose an intuitive name for easier retrieval. The system will not allow duplicate File Spec names.

3. Specify File Format

Select one of the following formats and click the Select button:

The file spec is created and nodes can be added as needed. When all nodes have been added, click Save to store the file spec.

Primary Specs

A Primary Spec is needed in order to configure the format of a WebSphere Product Center catalog structure. The primary spec is mapped to a file spec, defining how information should be routed from data source to the catalog. Primary specs are also used to define hierarchies associated to catalogs.

Creating a Primary spec

1. Select Spec Type - By default, File Spec displays in this step.

2. Select Name - Enter a unique name for the primary spec and click Next to display the spec tree.

3. Define the primary spec with nodes defined with parameters as needed.  

4. Set Primary Key Field - A unique identifier is required when creating a catalog spec. Select a node as the primary key by clicking on the checkbox. A primary key must be identified before the spec can be saved.

5. When all attributes have been added, click Save to store the spec. 

Note: Once a primary key is selected and the spec has been saved, the primary key cannot be changed. If a new primary key needed, create a new spec.

Hierarchy Specs

Hierarchies (or Taxonomies) are used in WebSphere Product Center with catalogs as a way to classify the items that are stored within. It can be compared to how library books are placed in certain areas of the building, such as "Non-Fiction", "Reference" and "Periodicals." The books are classified in a way that makes them easier to browse, both for the library patrons and for the librarians.

In the same way that a librarian uses this categorization scheme, WebSphere Product Center provides users with the tools to build and modify multiple hierarchies to help them organize the items stored within their catalogs.

Before hierarchies can be created, it must have an associated Primary Spec. Once a Primary Spec has been created, a hierarchy can be built using the Hierarchy Console.

Create Hierarchy Spec

Creating a hierarchy spec is the same as creating a primary spec. Use the same instructions as creating a primary spec.

Build Destination Spec

When an export job is created in WebSphere Product Center, a destination spec is created to define the exact requirements of the destination file. Similar to a file spec or primary spec, each attribute of the destination spec is defined. During the exportation of data, the destination spec generates a file that adheres to a set of predefined requirements.

A set of pre-defined destination specs is available (i.e. Ariba, Yahoo Shopping, Commerce One) and is not editable.

Create Destination Spec

1. Select Spec Type - By default, Destination Spec displays in this step.

2. Select Name - Enter a unique name for the destination spec and click Next to display the spec tree.

3. Define the destination spec with nodes defined with parameters as needed.  

4. When all attributes have been added, click Save to store the spec. 

When creating an export, a primary spec can be mapped to the destination spec. All available destination specs are displayed when creating a Spec Map or an Export job.


Spec imports and exports

Any spec can be imported and exported from the Specs Console. Specs can be exported in XML or XSD formats and can be imported into another WebSphere Product Center instance. The export feature is a great way to back up all specs so they do not have to be recreated from scratch.

Importing a spec

1. Select a spec type from the spec navigation bar and click on the Import button. The "Upload of a Spec XML or XSD" appears in a separate window. To import all the currently displayed specs appearing in the Spec Console, click the All checkbox.

Note: The spec type of the imported spec file must be selected. If Primary is selected in the Specs Console and the user attempts to import a File Spec, an error occurs.

2. If selecting a XML Document, click Browse and select a file to import then click Upload. The document is stored in the Document Store.

3. If selecting an XSD Schema Definition, the "XSD Options" section appears. Enter the required information and click Upload.

4. The imported spec appears in the Specs Console. If an error occurs, it is possible that the imported file type does not match that of the Spec Console.

Exporting a spec

Select a spec type from the spec navigation bar and select a spec to export from the Specs Console. To export all the currently displayed specs appearing in the Spec Console, click the All checkbox.

1. To export a spec, simple check the box next to the spec in the Specs Console and click on the Export XML or Export XSD button. The Specs Export Results interface appears.

2. A system-generated name is given to the exported spec and is stored in the Docstore. A new window appears providing details of the spec export results.

Note: If exporting to file type XML, it is saved to the docstore. If the same file is exported to file type XSD, it will overwrite the previous XML file and replaces it with the XSD file.

3. Click on the export file name hyperlink in the "Spec Export Results" window to view the spec file details. View the last modified information, view content link, and the audit log for the exported file.

Figure 14.6 - Spec export results

4. Click the "this link to docstore" hyperlink to navigate to the Docstore directory where the file was saved.


Spec Maps

Spec Maps are created to define how information from one source is going to route to another source. For example, a catalog spec, which defines the fields of a catalog, is mapped to a destination spec, which defines the fields of a destination. Therefore, when the catalog is exported using the Catalog spec to Destination Map, the information is routed in the proper structure.

Spec Map Console

The Mapping Console displays all of the previously created maps of the following types:

The following are the icons in the Mapping Console.

 

Delete mapping

 

Edit mapping

 

View mapping

Create a new mapping

 The following are the columns in the Mapping Console

Type

Type of mapping

Name

User defined name for the map

Source

The source spec used

Destination

The destination spec used

Accessing the Spec Map Console

To access the Specs Console, use the menu path
Data Model Manager > Specs/Mappings > Specs Maps > Spec Map Console.

Creating Spec Map

All specs maps are created the same way. This section describes how to create a catalog to destination spec map. 

The Catalog to Destination Spec map is similar to the File to Catalog Map in that it instructs WebSphere Product Center with how the fields in the catalog should be routed during an export. The fields in a catalog are mapped to the fields of a destination file. This mapping is used when defining an export of the catalog to a destination.

1. Select spec map type - This defaults to the type of spec selected from the Spec Map Console

2. Select Catalog Source - Select the catalog that is to be exported and click Select.

3. Select Destination Spec - Select the destination spec that is to be used and click Next, the Source Mapping table appears.

4. Enter name for the spec map in the Enter map name field.

5. Select a node from the Selected Source Attribute drop-down field and click +ADD to map it to a destination attribute.

6. To add an expression to the mapped attributes, click the expression button. The "Scriptlet Editor" interface appears.

7. When all spec nodes have been added, click Save.