User-defined value set support in the UDDI registry

In UDDI V2 this was called 'Custom Taxonomy Support'.

Data is worthless if it is lost within a mass of other data and cannot be distinguished or discovered. If a client of UDDI cannot effectively find information within a registry, the purpose of UDDI is considerably compromised. Providing the structure and modeling tools to address this problem is at the heart of UDDI's design. The verification of data within UDDI is core to its mission of description, discovery and integration. It achieves this by several means.

It allows users to define multiple value sets that can be used in UDDI. In such a way, multiple classification schemes can be overlaid on a single UDDI entity. This capability allows organizations to extend the set of such systems UDDI registries support. One is not tied to a single system, but can rather employ several different classification systems simultaneously.

While default value sets are shipped with the product, the UDDI V3 Registry provides tools enabling 'custom' value sets to be added, potentially enabling UDDI entities to be more specifically categorized when published and further enhancing the capability of client to find specific data.

These value sets can be either checked or unchecked, and this is indicated via a keyedReference in the categoryBag of the tModel that represents a value set (a "categorization tModel"). These keyedReferences have the tModel key for uddi-org:types and are added to the categoryBag to further describe the behavior of the categorization tModel, as follows:

checked

Marking a tModel with this classification asserts that it represents a categorization, identifier, or namespace tModel that has a validation service to check that category values are present in a specified value set.

unchecked

Marking a tModel with this classification asserts that it represents a categorization, identifier, or namespace tModel that does not have a validation service.

The procedure defined below describes how to add additional user-defined value sets, and display their allowed values in the UDDI user console value set tree display. Rational Application Developer has a Web Services Explorer user interface that also allows addition and display of custom checked value sets. The publisher of a value set categorization tModel may specify a 'display name' for use in UDDI user console implementations.

 

Procedure for adding a user defined value set

To

add a user defined value set to the IBM WebSphere UDDI Registry requires you to perform three tasks:

  • publish a categorization tModel

  • load the user defined value set data

  • set the value set to supported status using the Administration console.

Only when all are complete will the checked value set be referenced. Value set data must be provided for validating checked value sets.

Value set data may also be used by user consoles for unchecked value sets, but it is not a requirement and is usually only used for presentation of deprecated value sets, such as unspc-org:unspc and back-level compatibility.

If the value set is checked, any publish requests that have a categoryBag containing keyedReferences with the new categorization tModel will be validated. If there is value set data corresponding to the categorization tModel in the registry database, only valid values will be accepted. If there is no value set data in the database all values will be rejected, and the publish request will fail. If the categorization tModel is unchecked, all values will be allowed, regardless of whether there is a corresponding value set present in the UDDI Registry database. The value set tModel is not available for use until the administrator enables support for it using the Administration console, or the JMX interface.

 

Suggested approach

To introduce a new value set:

  1. Publish the categorization tModel with a keyedReference of type 'uddi-org:categorization:types' with a key value of categorization, a keyedReference of type 'uddi-org:categorization:types' with a Key Name of 'Checked value set' and a Key Value of 'checked', or a Key Name of 'Unchecked value set' and a Key Value of 'unchecked' and a keyedReference of type 'uddi-org:categorization:general_keywords' supplying the value set display name (as described below).

  2. Load user defined value set data into the UDDI Registry database using the UDDIUserDefinedValueSet utility (described below).

  3. Use the Administration Console to set the status of the value set to supported (as described in Value set settings). This can also be achieved directly using the JMX interface.

Note: The SOAP and EJB interfaces will be able to make use of categorization tModels as soon as they are published. However, the UDDI Registry user console will require a restart of the UDDI application because it currently gathers its list of categorizations for use in the value set tree display when the application starts.

 

Publishing a Checked Categorization tModel

This section describes how to publish a checked categorization tModel with the 'Checked value set' Key Name for use by a user defined value set.

Publish a tModel to the IBM WebSphere UDDI Registry with a categoryBag containing keyedReferences as follows:

Note tModelKey KeyName KeyValue
1 uddi:uddi-org:categorization:types

In the UDDI Registry user interface this tModelKey can be chosen by selecting the category type of UDDI Types

categorization categorization
2 uddi:uddi-org:categorization:types

In the UDDI Registry user interface this tModelKey can be chosen by selecting the category type of UDDI Types

Checked value set checked
3 uddi:uddi-org:categorization:general_keywords

In the UDDI Registry user interface this tModelKey can be chosen by selecting the category type of categorization:general_keywords

urn:x-ibm:uddi:customTaxonomy:displayName <User Defined Value Set displayName>

  1. Indicates this tModel is a categorization tModel (required).

  2. Indicates use of the tModel will be checked against a list of valid data (required). (Omitting this keyedReference, or explicitly specifying a value of 'unchecked' will indicate this categorization is unchecked).

  3. Indicates special use of the general keywords value set, with a proprietary urn as the keyName value, defines a name for the user defined value set that is intended for use in user console implementations where the full tModel name might be too long. The value can be 1-255 characters (inclusive) long.

The displayName is intended to provide a way to label a value set such that, when the UDDI user console displays it in a value set tree or in a pull-down list of available value sets, the meaning is clear to the user without being restricted to 8 characters and without needing to be the same as the published tModelName, which could be as long as 255 characters. An example is shown below:

This diagram shows that the display name appears in both the taxonomies tree and the Types drop-down in the Locator section.

The urn:x-ibm:customTaxonomy:displayName should be unique if only to avoid confusion when displayed in user interfaces but this is not validated.

To publish a new categorization tModel using SOAP, the message would be

<save_tModel generic="3.0" xmlns="urn:uddi-org:api_v3">    
  <authInfo></authInfo>>
  <tModel tModelKey="">
    <name>Natural Foods tModel</name>
    <categoryBag>
      <keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName="categorization" keyValue="categorization"/>
      <keyedReference tModelKey="uddi:uddi.org:categorization:types" keyName="Checked value set" keyValue="checked"/>
      <keyedReference tModelKey="uddi:uddi.org:categorization:general_keywords" keyName="urn:x-ibm:uddi:customTaxonomy:displayName" keyValue="Natural Foods"/>
    </categoryBag>
  </tModel>  
</save_tModel>

Note: to specify an unchecked categorization substitute the key name 'Checked value set' with 'Unchecked value set' and 'checked' Key Value with 'unchecked' or, more simply, omit the keyedReference completely.

 

Loading User Defined Value Set Data

User Defined Value Set Data File Format

Value set data is identified by a unique code value, an optional description and a parent code that specifies its relationship with other code values. Value set data must adhere to this format:

Column name Maximum length Description of use
Code 765 Unique value within the value set used for validation
description 765 Typically used by UDDI user consoles and optionally in the keyedReference as the keyName value
parentcode 765 Indicates which existing code is the logical parent of this one, and is used in tree displays
Typically columns are delimited in the value set data file by '#' characters as in this example

00#Food#00
10#Fruit#00
101#Apples#10
102#Oranges#10
103#Pears#10
1031#Anjou#103
1032#Conference#103
1033#Bosc#103
104#Pomegranates#10
20#Vegetables#00
201#Carrots#20
202#Potatoes#20
203#Peas#20
204#Sprouts#20

In the example, 'Food' is the description for the root node with child nodes of 'Fruit' and 'Vegetables' (both of these have parentcode values the same as the code value for 'Food').

The value set data in the example file could then be rendered in a tree like this

Food
  Fruit
    Apples
    Oranges
    Pears
      Anjou
      Conference
      Bosc
    Pomegranates
  Vegetables
    Carrots
    Potatoes
    Peas
    Sprouts

The file must be saved in UTF-8 format.

Custom Taxonomy files used in UDDI V2 are also supported by the utility.

UDDIUserDefinedValueSet

A utility is provided to load value set data into the IBM WebSphere UDDI Registry, assign existing value set data to another tModel and unload existing value set data. This utility uses the UDDI Registry's JMX interface and therefore requires a number of connection parameters

Usage: UDDIUserDefinedValueSet[.sh|.bat] '{'function'}' [options]

function:
-load <path> <key>         Load value set data from specified file
-newKey <oldKey> <newKey>  Move value set to a new tModel
-unload <key>              Unload existing value set

options:
-properties <path>         Specify location of configuration file
-host <host name>          Application Server or Deployment Manager host
-port <port>               SOAP Lister port number
-node <node name>          Node running a UDDI server
-server <server name>      Server with UDDI deployed
-columnDelimiter <delim>   Character delimiter to denote field end
-stringDelimiter <delim>   Character delimiter to denote strings


Connector security parameters

-userName <name>
-password <password>
-trustStore <path>
-trustStorePassword <password>
-keyStore <name>
-keyStorePassword <password>

Note: Ensure that the command window from which the UDDIUserDefinedValueSet is run is using a suitable codepage and font for displaying the characters contained in the value set name. Use of an incorrect codepage/font may result in unclear messages on a successful load, and create difficulty using the -unload and -newKey options.

The UDDIUserDefinedValueSet.bat script (for Windows) or UDDIUserDefinedValueSet.sh script (for Unix platforms) is located in the install_root/bin directory.

If no connection parameters are supplied a connection is sought on the local host using firstly the Deployment Managers default SOAP port number, and, if there is no Deployment Manager running, the default Application Server SOAP port number.

Command arguments are case insensitive.

Usage examples

Load a value set data for a tModel on the local UDDI Registry using the '%' sign as a column marker in the valuesetdata.txt file:

UDDIUserDefinedValueSet.xxx -load valuesetdata.txt uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe -columnDelimiter %

where .xxx is .bat for Windows or .sh for Unix platforms.

Move value set data from one checked tModel to another on a UDDI Registry in a Network Deployment:

UDDIUserDefinedValueSet.xxx –newKey uddi:a708b8a7-35b5-451c-aafc-718ae071fcfe uddi:b819c9b8-46c6-562d-bb0d-829bf1820d0f –host depmanagerhost.ibm.com –port 8879 –node uddinode –server uddiserver -override

where .xxx is .bat for Windows or .sh for Unix platforms.

Unload a value set from a tModel from a server with security turned on supplying the connection and security parameters in myproperties.properties file, but supplying the server and password arguments on the command line (which augment or override those contained in the properties file):

UDDIUserDefinedValueSet.xxx –unload uddi:b819c9b8-46c6-562d-bb0d-829bf1820d0f –server uddiserver –properties myproperties.properties –password myrealpassword 

where .xxx is .bat for Windows or .sh for Unix platforms.

The configuration file, if specified by the optional -properties parameter, determines a number of optional parameters. These parameters can be specified on the command line and, if so, override the values in the properties file. These parameters are largely JMX connection parameters and security parameters.

The string.delimiter is typically used where a description value contains the same character as the column delimiter character. For example, if the column.delimiter was set to ',' (a comma), and there was a value set description value of 'Fruits, citrus', you could include this in the value set data file by setting the string.delimiter to " (double quote) and enclosing the description in quotes: 'Fruits, citrus'. Note that the quote character is escaped with a backslash ('\') to indicate the literal character is to be used.

If an attempt is made to load a value set to a tModel that has existing value set data, a warning message is given. To override this error provide the -override argument. This argument is also required if moving value set data to a new tModel using -newKey where the tModel is checked, and also unloaded value set data for a checked tModel.

Command line arguments and example data Property and example data Comments
-columnDelimiter # column.delimiter=# Column delimiter used in value set data files
-stringDelimiter \" string.delimiter=\" Field delimiter (must be different to the column.delimiter value
-host ibm.com host=ibm.com Host name of the system running Deployment Manager or Application Server
-port 8880 port=8880 SOAP port number of Deployment Manager or Application Server
-node ibmNode node=ibmNode Name of the Node running the server with the UDDI Registry
-server server1 server=server1 Server running the UDDI Registry
-userName ibmuser security.username=ibmuser User name. Required if WebSphere security is turned on
-password mypassword security.password=mypassword Password
-trustStore /TrustStoreLocation security.truststore=/TrustStoreLocation Truststore file location
-keyStore ibmkeystore security.keystore=ibmkeystore Keystore name
-trustStorepassword trustpass security.truststore.password=trustpass Truststore password
-keyStorePassword keypass security.keystore.password=keypass Keystore password

 

Set the value set to supported

Use the Administration

console to set the value set to supported by:

  • Click UDDI Nodes > <node> and Value Sets (under Additional Properties on the right of the screen)

  • Select the Value Set (by checking the box next to it)

  • Click Enable Support above the list of Value Sets

 

Validation and Error Handling

The UDDI Registry user console performs validation while a save tModel request is being built, that is, before the publish occurs. For example, if the user tries to add two customTaxonomy:displayName keyedReferences the following message is displayed:

Advice: Only one 'urn:x-ibm:uddi:customTaxonomy:displayName' key name is allowed for the 'Other' taxonomy.

If a keyedReference containing a keyName value that starts with 'urn:x-ibm:uddi:customTaxonomy:' is followed by anything other than 'displayName', the following message is displayed:

Advice: Only key name values of 'urn:x-ibm:uddi:customTaxonomy:displayName' are supported.

For requests where the save_tModel message may have multiple tModels, if any one of the tModels is a categorization tModel and it fails validation, the request fails with a UDDIInvalidValueException (plus additional information explaining the likely cause), and none of the tModels is published. For example:

E_invalidValue (20200) A value that was passed in a keyValue attribute did not pass validation.  This applies to checked categorizations, identifiers and other validated code lists. The error text will clearly indicate the key and value combination that failed validation. Invalid 'customTaxonomy:dbKey' keyValue [naics] in keyedReference. KeyValue already in use by tModelKey[UUID:C0B9FE13-179F-413D-8A5B-5004DB8E5BB2]