Home > Tutorial

Design an Adaptation Model

The adaptation model used by webMethods MDM is a standard file widely accepted in the market as XML Schema.

The purpose of an XML Schema is to define the legal building blocks of an XML document. This XML document contains the Master Data to be managed by webMethods MDM.

In the following chapters, we will step by step describe the creation of the model in XML Schema, corresponding to the publications database.

Schema skeleton

The simplest version of a Schema used by webMethods MDM is described here:

<?xml version="1.0" encoding="UTF-8"?> 
<!----> 
<!--   Copyright © Software AG 2000-2006. All rights reserved. --> 
<!----> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 

	xmlns:mdm="urn:mdm-schemas:common_1.0" xmlns:fmt="urn:mdm-schemas:format_1.0" 

	xmlns:mdmbnd="urn:mdm-schemas:binding_1.0"> 

	    <xs:import namespace="urn:mdm-schemas:common_1.0" 

	schemaLocation="http://schema.softwareag.com/common_1.0.xsd"/> 

	    <xs:element name="root" mdm:access="--"> 
    </xs:element> 
</xs:schema>

All useful namespaces are declared at the beginning of the document,
A single element is declared as the root of the model (called ‘root’ in our example). This element has an attribute mdm:access that specifies the access rights for this node. These rights may be set to nothing (“--“).

Reusable types

For each table defined in the database, we will create an element type that can be reusable across the Schema. This also simplifies the document structure.

Let’s start with the Publisher table. This table is defined as a complex type that describes a sequence of elements which are the original table fields:

pub_id, which is a mandatory 4 characters string type element and follows a specific pattern
name, which is a mandatory 40 characters string type element
city, which is an optional 20 characters string type element

The corresponding complex type, named Publisher, may be defined as:

<xs:complexType name="Publisher"> 
        <xs:sequence> 
            <xs:element name="pub_id"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="4"/> 
                        <xs:pattern value="[0-9]{4}"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
            <xs:element name="name"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="40"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
            <xs:element name="city" minOccurs="0"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="20"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
        </xs:sequence> 
</xs:complexType>

Please note that:

all standard field types are supported in XML schema. Hence any type defined in a database, who ever the vendor is, is supported in the target model,
any optional element is declared with the minOccurs="0" attribute (or nillable="true"),
any pattern may be specified using the xs:pattern element

Root element

Let’s now enrich the root element with a child node called Publishers, which defines the table records (minOccurs="0" maxOccurs="unbounded") and is of the previously created Publisher named type.

<?xml version="1.0" encoding="UTF-8"?> 
<!----> 
<!--   Copyright © Software AG 2000-2006. All rights reserved. --> 
<!----> 
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 

	xmlns:mdm="urn:mdm-schemas:common_1.0" xmlns:fmt="urn:mdm-schemas:format_1.0" 

	xmlns:mdmbnd="urn:mdm-schemas:binding_1.0"> 

	    <xs:import namespace="urn:mdm-schemas:common_1.0" 

	schemaLocation="http://schema.softwareag.com/common_1.0.xsd"/> 
 
	
    <xs:element name="root" mdm:access="--"> 
        <xs:complexType> 
            <xs:sequence> 

                <xs:element name="Publishers" type="Publisher" minOccurs="0" maxOccurs="unbounded"/> 

	            </xs:sequence> 
        </xs:complexType> 
    </xs:element> 
 

		    <xs:complexType name="Publisher"> 

	        <xs:sequence> 
            <xs:element name="pub_id"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="4"/> 
                        <xs:pattern value="[0-9]{4}"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
            <xs:element name="name"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="40"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
            <xs:element name="city" minOccurs="0"> 
                <xs:simpleType> 
                    <xs:restriction base="xs:string"> 
                        <xs:maxLength value="20"/> 
                    </xs:restriction> 
                </xs:simpleType> 
            </xs:element> 
        </xs:sequence> 
    </xs:complexType> 
</xs:schema>

Intermediary schema

The same modelling process can be pushed further to define the other tables and related complex named types.
Please note that in the Titles table, only specific values are allowed for field named type. This can be implemented using the XML Schema enumeration declaration:

<xs:element name="type" default="Unknown"> 
    <xs:simpleType> 
        <xs:restriction base="xs:string"> 
            <xs:maxLength value="30"/> 
            <xs:enumeration value="Business &amp; Technology"/> 
            <xs:enumeration value="Arts &amp; Entertainment"/> 
            <xs:enumeration value="Fiction"/> 
            <xs:enumeration value="Health &amp; Spirituality"/> 
            <xs:enumeration value="Lifestyle, Family &amp; Home"/> 
            <xs:enumeration value="Non fiction"/> 
            <xs:enumeration value="Recreation"/> 
            <xs:enumeration value="Unknown"/> 
        </xs:restriction> 
    </xs:simpleType> 
</xs:element>

Please note that:

the ‘&’ symbol is not permitted in XML Schema document as it is internally used for other purposes. It may be changed to ‘&’ to prevent a syntax error.
default value is specified using the default attribute
among an enumeration, allowable attribute is "value" (which specifies the value that is suggested to the webMethods Master Data Manager user), but attribute "id" may be also used, hence allowing to persist an integer value corresponding to the user choice, which significatively reduces the amount of data stored in the master data repository. If no id attribute is specified, the value attribute will be persisted instead.

The intermediary XML Schema for our Publications sample database is available here.

Important note:

As of now, each time the schema is updated with new features described in the following chapter, you have to refresh the model to take the amendments into account in webMethods Master Data Manager (‘Refresh model’ link at the top of the user screen in development mode).

webMethods MDM specific features

We just went through the definition of every elements corresponding to each table in the database. Our modelling task is not ended at this point, as we need to enrich the model with specific functionalities that XML Schema does not natively support.

webMethods MDM Module

Before going further in the design, let’s take some time to introduce the concept of modules in MDM.

An webMethods MDM Module allows the packaging of an adaptation model with additional resources (default message files, default formats, included XML Schemas, etc..)

On a J2EE application server, an webMethods MDM Module is integrated into a Web application. This provides Web applications features such as: class-loading isolation, WAR or EAR packaging, static Web resources exposition, hot-redeployment. In addition, if your user application is a Web application, it is possible to merge the webMethods MDM module with your application, in order to simplify deployment.

In our example, we will create a ‘books’ module packaging all necessary resources for the correct execution. The module structure looks like the following:

/WEB-INF/mdm/
This directory contains all description and configuration files for using webMethods MDM.
/WEB-INF/mdm/module.xml
This file defines the global properties of the webMethods MDM module:

<?xml version="1.0" encoding="UTF-8"?> 

        <module xmlns="urn:mdm-schemas:module_2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mdm-schemas:module_2.1 http://schema.softwareag.com/module_2.1.xsd"> 

            <name>Book Publishers</name> 

            <publicPath>pubs</publicPath> 

            <locales> 

                <locale isDefault="true">en_US</locale> 

                <locale>fr_FR</locale> 

            </locales> 

        </module>

/WEB-INF/mdm/schema/pubs.xsd
This file defines the adaptation model (XML Schema document) of the webMethods MDM tutorial module. It contains all the model definition we created so far.
/WEB-INF/web.xml
This file ensures module registration at application server launch:

<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> 
<web-app> 
    <servlet> 
        <servlet-name>BooksPublishersModule</servlet-name> 
        <description> 
            This servlet is used for registering this web application as an webMethods MDM module. 
            In its init() method, it must call "ModulesRegister.registerWebApp()". 
            You may create a dedicated servlet like here, or reuse an existing servlet. 
        </description> 
        <servlet-class>com.softwareag.mdm.tutorial.module.RegisterServlet</servlet-class> 
        <!-- 
            load-on-startup is required for the webMethods MDM registration to be done 
            even without having started this web application (it is necessary 
            if webMethods Master Data Manager is used before an application using adaptations is called). 
          --> 
        <load-on-startup>1</load-on-startup> 
    </servlet> 
</web-app>

/WEB-INF/mdm/module.properties (Optional)
This files defines additional properties
/www/
This directory contains all external resources (accessible by URL). This directory is optional, localized and structured by resource type (html, images, jscripts, stylesheet). External resources in this directory can be referenced in adaptation models (parameters of type resource).

Once the structure is created, we need to register the module within webMethods MDM. For that purpose, we implement a specific Java class we call RegisterServlet in our example. This class is referenced in /WEB-INF/web.xml under the < servlet-class> element.

/* 
 * Copyright © Software AG 2000-2007. All rights reserved. 
 */ 
package com.softwareag.mdm.tutorial.module; 

import javax.servlet.*; 
import javax.servlet.http.*; 

import com.softwareag.mdm.base.repository.*; 

public class RegisterServlet extends HttpServlet 
{ 
    public void init(ServletConfig config) throws ServletException 
    { 
        super.init(config); 
        ModulesRegister.registerWebApp(this, config); 
    } 
    public void destroy() 
    { 
        ModulesRegister.unregisterWebApp(this, this.getServletConfig()); 
    } 
} 

As you can see, the only purpose of this class is to register/unregister a new servlet inside the application server. This way, our new module is known by webMethods MDM and will be managed accordingly.

Specify Tables

So far, we have not specified anywhere in our schema that the elements are of table type. This can be done using Table declarations.

In order to declare the primary keys of a table, webMethods MDM uses the primaryKeys element under an xs:annotation/xs:appinfo/mdm:table element. We can define as many key fields as needed in this element, using a space character between them. Each field specified refers to one or more of the table elements using its path.

Example: Define pub_id as the primary key of table Publishers

We declare the primaryKeys element under the Publisher complexType.

<xs:complexType name="Publisher"> 

            <xs:annotation> 

        <xs:appinfo> 

            <mdm:table> 

                <primaryKeys>/pub_id</primaryKeys> 

            </mdm:table> 

        </xs:appinfo> 

    </xs:annotation> 

            <xs:sequence> 

                <xs:element name="pub_id"> 

                    <xs:simpleType> 

                        <xs:restriction base="xs:string"> 

                            <xs:maxLength value="4"/> 

                            <xs:pattern value="[0-9]{4}"/> 

                        </xs:restriction> 

                    </xs:simpleType> 

                </xs:element> 

                <xs:element name="name"> 

                    <xs:simpleType> 

                        <xs:restriction base="xs:string"> 

                            <xs:maxLength value="40"/> 

                        </xs:restriction> 

                    </xs:simpleType> 

                </xs:element> 

                <xs:element name="city" minOccurs="0"> 

                    <xs:simpleType> 

                        <xs:restriction base="xs:string"> 

                            <xs:maxLength value="20"/> 

                        </xs:restriction> 

                    </xs:simpleType> 

                </xs:element> 

            </xs:sequence> 

        </xs:complexType>

Once all complex types are correctly amended with the correct primary keys in the Schema, webMethods MDM will ensure that no identical records are created.

Moreover, in the case where a table field refers to another in a different table, foreign keys ensure the data integrity is respected, preventing the selection of a value not defined in the spectrum of the allowable values.
Foreign key definition is described in the following chapter.

Presentation informations

As you know, the user interface in webMethods Master Data Manager is dynamically generated from the XML Schema and may be localized in a multilingual environment.

For this purpose, every single element in the schema must be declared with all localization information. This way, all language-dependant presentation is packaged in the schema and will be used by webMethods Master Data Manager to render the information with the correct translation, depending on the user language preference.

An element may be declared with all translation information sitting under its xs:annotation/xs:documentation element.
The documentation element accepts the attribute xml:lang that specifies the language in which the information is translated.
All localization languages are defined in common_1.0.xsd schema.

Label and description

The label displayed by webMethods Master Data Manager for a given schema element is specified by an mdm:label element. This label will be used for the column name in the table.

An mdm:description element may also be specified and rendered in the information part of the webMethods Master Data Manager user interface (displayed after a click on the icon).

Example: Localize label and description elements for field name in table Publishers.

All elements in our sample database may be localized both in English (xml:lang="en-US") and French (xml:lang="fr-FR").

<xs:element name="name"> 

            <xs:annotation> 

        <xs:documentation xml:lang="fr-FR"> 

            <mdm:label>Nom</mdm:label> 

            <mdm:description>Nom de l'éditeur</mdm:description> 

        </xs:documentation> 

        <xs:documentation xml:lang="en-US"> 

            <mdm:label>Name</mdm:label> 

            <mdm:description>Publisher name</mdm:description> 

        </xs:documentation> 

    </xs:annotation> 

            <xs:simpleType> 

                <xs:restriction base="xs:string"> 

                    <xs:maxLength value="40"/> 

                </xs:restriction> 

            </xs:simpleType> 

        </xs:element>

And the following rendering in the French locale:

And in the English locale:

Next: Define Advanced Constraints >

Home > Tutorial

Copyright © Software AG 2000-2007. All rights reserved.
Trademarks and brand names referred to in this web site relating to organizations
other than Software AG are the property of those organizations
and Software AG makes no claims to such property.