Constraints, Triggers and Functions

Facets allows you to define constraints on your Master Data in your schemas. webMethods MDM supports XML Schema facets and provides extended and programmatic facets for advanced data controls.

XML Schema facets Standard XML Schema constraints	Extended Facets Advanced declarative constraints	Programmatic Facets Develop your own Java constraints	Triggers and Functions Feed values automatically
XML Schema Supported facets	Dynamic constraints FacetOResource constraint excludeValue constraint excludeSegment constraint Enumeration facet filled by another node Integrity constraint (Table)	Programmatic constraints Programmatic enumeration constraints Programmatic nomenclature constraints Constraint on null value	Computed values Triggers Auto incremented values

 

XML Schema Supported facets
 

	length	min Length	max Length	pattern	enum- eration	white Space	fraction Digits	max Inclusive	max Exclusive	min Inclusive	min Exclusive
string	X	X	X	X	X	(1)		(2)	(2)	(2)	(2)
boolean				X		(1)
decimal				X	X	(1)	X	X	X	X	X
dateTime				X	X	(1)		X	X	X	X
time				X	X	(1)		X	X	X	X
date				X	X	(1)		X	X	X	X
anyURI	X	X	X	X	X	(1)
Name	X	X	X	X	X	(1)		(2)	(2)	(2)	(2)
integer				X	X	(1)	X	X	X	X	X
resource (3)

Notes :

• (1) The whiteSpace facet can be defined, but is not interpreted by webMethods MDM
• (2) In XML Schema, boundary facets are not allowed on the type String. Nevertheless, webMethods MDM allows those facets as extensions.
• (3) The resource type supports only one facet (required): FacetOResource (see webMethods MDM Extended Facets).

Example:

Extended Facets

webMethods MDM provides additional constraints that are not specified in XML Schema, but that are useful for Master Data Management.

In order to guarantee the conformance with XML Schema, those Extended Facets are defined under the element annotation/appinfo/otherFacets.

Dynamic constraints

Those facets keep the XML Schema semantic, but value attribute is replaced by a path attribute that allows to get the value from another Master Data in the adaptation:

• length
• minLength
• maxLength
• maxInclusive
• maxExclusive
• minInclusive
• minExclusive

By the mean of these facets, the data model may be modified dynamically, in the adaptations.

Example :

In this example, the boundary of the facet minInclusive is not defined statically. The value of the boundary comes from the node /domain/Loan/Pricing/AmountMini/amount

FacetOResource Constraint

This facet must be defined for each resource type. It has the following attributes:

• moduleName: indicates with an alias which webMethods MDM module contains the resource. If it is the module itself that contains the resource, the alias must be preceded by "wbp". Otherwise, the alias must be one of the values defined in the element <dependencies> of the file‘module.xml’ ;
• resourceType: represents the resource type that is one of the following values: "ext-images", "ext-jscripts", "ext-stylesheets", “ext-html”;
• relativePath: represents the local directory where to find the resource, just under the "resourceType" directory. In the example below, it is the directory www/common/images/. Hence, for this example, the resource is located at www/common/images/promotion/ where the www/ directory is at the same level than the WEB-INF/ directory.

This facet has the same behavior as an enumeration facet: the values are collected by listing recursively all the files in ‘local path’ from the specified directory ‘resource type’ in the specified ‘module’ .

Example :

An overview of directories structures in an webMethods MDM module (J2EE webApp) is detailed in the section webMethods MDM Modules - Structure.

excludeValue constraint

This facet verifies that an instance is different from a specified value.

Example :

In this example, the empty string is excluded from possible values.

excludeSegment constraint

This facet verifies that an instance is not included in a segment of values. Boundaries are excluded.

Example :

In this example, values between 20000 and 20999 are excluded.

Enumeration facet filled by another node

By default, an enumeration facet is described statically in XML Schema.
The content of an enumeration facet can be filled dynamically by another node of the adaptation model.

Filling by a list

With the following information, we indicate that the content of an enumeration facets comes from the node ‘CountryList’.

The node ‘CountryList’ :

• Must be from the same type that the node that has the enumeration facet
• Must be multiple (maxOccurs="unbounded").

Example :

Integrity constraint (Table)

A reference to a table is defined using the extended facet tableRef. The element must be of type xs:string.

Element	Description	Required
container	reference of the instance that contains the table.	No, default is current instance.
tablePath	XPath expression that specifies the table.	Yes.
labelPaths	XPath expressions that specify the composition of the label.	No, default label is the primary key.
displayKey	"true" or "false", specifies whether key is displayed as label prefix.	No, default is "true".

The example below specifies a reference (foreign key) to an occurrence of ‘catalog’ element.

At runtime, extended facet tableRef is interpreted as an enumeration whose values are formatted foreign keys. Labels may be added to key value by using labelPaths element: each label is specified by the absolute path in the content of an occurrence.

Programmatic Facets

A programmatic constraint may be added on any XML element declaration that refers to a simple type.

In order to guarantee the conformance with XML Schema, those constraints are specified under the element annotation/appinfo/otherFacets.

Programmatic constraints

A programmatic constraint is defined by a Java class that implements the interface com.softwareag.mdm.schema.Constraint.

Additional parameters can be defined. Consequently, the java class implemented must conform to the JavaBean protocol. In the example below, the java class must define methods: getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Example :

Programmatic enumeration constraints

An enumeration constraint adds to a basic programmatic constraint the definition of an ordered list of values. Such a constraint is defined by a Java class that implements the interface com.softwareag.mdm.schema.ConstraintEnumeration. This facet allows selecting a value into a list.

Example :

Programmatic nomenclature constraints

A nomenclature constraint adds to a basic programmatic constraint the definition of an ordered list of value-labels (see Nomenclature). Such a constraint is defined by a Java class that implements the interface com.softwareag.mdm.schema.ConstraintNomenclature. This facet allows selecting a value into a list.

Note that an enumeration constraint is more appropriate when display must be localized or when there are many values in the enumeration.

Example :

Constraint on null value

A programmatic constraint is not checked against a null value. In order to check if a null value is allowed in the context of an adaptation, a specific constraint must be defined by a Java class that implements the interface com.softwareag.mdm.schema.ConstraintOnNull.

Constraint on null value applies on a node declaration with attributes: minOccurs="0" and maxOccurs="1".

According to Manager tool validation policy, null constraint is not checked on user input, but on adaptation validation only. If a null value must be checked on user input via Manager tool, element must define a mdm:checkNullInput attribute to true.

Example :

 

Triggers and Functions

Computed values

By default, Master Data are read and persisted in the XML repository. Nevertheless, they may be the result of a specific computation and/or access to an external database (a RDBMS, a central system...).

webMethods MDM even allows to take into account other Master Data in the current adaptation context.

This is made possible by defining functions.

A function is specified in XML Schema document by using the element mdm:function (see example below).

• The value of class attribute must be the qualified name of a Java class which implements the Java interface com.softwareag.mdm.adaptation.ValueFunction.
• Additional parameters may be specified at schema level, in this case JavaBeans convention is applied.

Example:

 

Triggers

One can associate to adaptation instances or to table occurrences methods that are automatically executed when some operations are performed: creation, update, delete, etc.

In XML Schema document, these triggers must be declared under the annotation/appinfo element using the mdm:trigger tag.

For adaptation instances triggers, we have to define inside the mdm:trigger tag a java class that extends the abstract class com.softwareag.mdm.schema.trigger.InstanceTrigger.

Note that in adaptation instances triggers case, it is advised to define annotation/appinfo/mdm:trigger tags just under the root element of the considered XML schema.

Example:

For tables occurrences triggers definition, we have to define inside the mdm:trigger tag a java class that extends the abstract class com.softwareag.mdm.schema.trigger.TableTrigger.

In table occurrences triggers case, it is advised to define the annotation/appinfo/mdm:trigger tags just under the element describing the considered table or table type.

Examples:

On a table element:

or on a table type element:

Note that additional parameters can be defined. Consequently, the java class implemented must conform to the JavaBean protocol. In the example above, the java class must define methods: getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Auto incremented values

It is possible to define auto incremented values. Auto incremented values are only allowed inside a table and they must be of type xs:int or xs:integer.

An auto increment is specified in XML Schema document by using the element mdm:autoIncrement under the element tag annotation/appinfo.

Example:

There are two optional elements start and step.

Example:

The start attribute specifies the first value for this auto increment. If this attribute is not specified, then the value "1" is set by default.

The step attribute specifies the step for the next value to be generated by the auto increment. If this attribute is not specified, then the value "1" is set by default.

Note: if a programmatic update specifies a value, for example during an import, auto increment is not executed.

Contraintes, triggers et fonctions

Les facettes permettent de définir des contraintes sur les Master Data dans les modèles d'adaptation. webMethods MDM supporte les facettes XML Schema et fournit des facettes étendues et programmatiques afin de définir des contrôles avancés.

Facettes XML Schema Contraintes standards XML Schema	Facettes étendues Contraintes déclaratives avancées	Facettes programmatiques Développez vos propres contraintes	Triggers et fonctions Alimentez les valeurs automatiquement
Facettes XML Schema supportées	Contraintes dynamiques Contrainte FacetOResource Contrainte excludeValue Contrainte excludeSegment Facette énumération alimentée par un autre noeud Contraintes d'intégrité (Table)	Contraintes programmatiques Contraintes programmatiques de type Enumeration Contraintes programmatiques de type Nomenclature Contrainte sur valeur nulle	Valeurs calculées Triggers Valeurs auto incrémentées

 

Facettes XML Schema supportées
 

	length	min Length	max Length	pattern	enum- eration	white Space	fraction Digits	max Inclusive	max Exclusive	min Inclusive	min Exclusive
string	X	X	X	X	X	(1)		(2)	(2)	(2)	(2)
boolean				X		(1)
decimal				X	X	(1)	X	X	X	X	X
dateTime				X	X	(1)		X	X	X	X
time				X	X	(1)		X	X	X	X
date				X	X	(1)		X	X	X	X
anyURI	X	X	X	X	X	(1)
Name	X	X	X	X	X	(1)		(2)	(2)	(2)	(2)
integer				X	X	(1)	X	X	X	X	X
resource (3)

Notes :

• (1) La facette whiteSpace peut être définie, mais n’est pas interprétée par webMethods MDM.
• (2) Dans XML Schema, les facettes ‘boundary’ ne sont pas autorisées sur le type string, néanmoins webMethods MDM les autorise en tant que extensions.
• (3) Le type resource supporte une seule facette (obligatoire) MDM, FacetOResource (cf Facettes Etendues).
• (4) D’autres types supportent les mêmes facettes que le type dont ils dérivent. Par exemple, le type integer supporte les mêmes facettes que le type decimal.

Exemple:

 

Facettes étendues

webMethods MDM fournit des contraintes avancées qui ne sont pas définies dans XML Schema mais sont utiles pour le Master Data Management.

Afin de conserver la conformité du document par rapport à la norme XML Schema, ces facettes sont définies sous l’élément annotation/appinfo/otherFacets.

Contraintes dynamiques

Les facettes suivantes supportent le référencement de la valeur d’un autre noeud :

• length
• minLength
• maxLength
• maxInclusive
• maxExclusive
• minInclusive
• minExclusive

Cette propriété permet de modifier les contraintes du modèle de données dynamiquement, dans les adaptations ou même dans un contexte.

Par rapport aux facettes standards, le nom de l’élément est conservé, cependant l’attribut statique value est remplacé par l’attribut path.

Exemple :

Dans cet exemple, la borne de la facette minInclusive n’est pas définie statiquement, la valeur de la borne est détenue par le nœud "/domain/Loan/Pricing/AmountMini/amount".

Contrainte FacetOResource

La facette doit être définie pour chaque type resource. Elle a les attributs suivants :

• moduleName : indique via un alias quel module contient la ressource. Si c’est le module lui-même qui possède la ressource, alors l’alias doit être “wbp”. Sinon, l’alias doit être l’une des valeurs définies dans l’élément <dependencies> du fichier ‘module.xml’;
• resourceType : désigne le type de la ressource qui peut être : "ext-images", "ext-jscripts", "ext-stylesheets", “ext-html”;
• relativePath : représente le répertoire local o se trouve la ressource, situé juste en-dessous du répertoire correspondant au type de cette ressource ("resourceType"). Dans l'exemple ci-après, il s'agit du répertoire www/common/images/. Ainsi, pour cet exemple, la ressource est située dans le répertoire www/common/images/promotion/. Notons que le répertoire www/ est au même niveau que le répertoire WEB-INF/.

Cette facette a le même comportement qu’une facette énumération : l’ensemble des valeurs est obtenu en listant récursivement tous les fichiers situés dans ‘local path’ du répertoire spécifié ‘resource type’ dans le ‘module’ spécifié.

Exemple :

Un aperçu de la structure des répertoires dans un module webMethods MDM (webApp J2EE) est donné dans la rubrique Modules webMethods MDM - Structure. Comme les ressources sont localisées, cet exemple indique que le répertoire promotion est (au moins) localisé en “fr_FR”.

Contrainte excludeValue

Cette facette vérifie qu’une instance est différente d’une valeur donnée.

Exemple :

Ici la chaîne vide est exclue des valeurs possibles.

Contrainte excludeSegment

Cette facette vérifie qu’une instance n’appartient pas à un segment de valeurs. Les bornes elles-mêmes sont exclues.

Exemple :

Ici les valeurs comprises entre 20000 et 20999 sont exclues.

Facette énumération alimentée par un autre noeud

Par défaut, une facette énumération est décrite statiquement en XML Schema.
Le contenu de la facette énumération peut être alimenté par un autre nœud du modèle de données.

Alimentation par une liste

En ajoutant l’information suivante, on indique que le contenu de la facette énumération provient du nœud frère ‘CountryList’.

 

Le nœud frère ‘CountryList’ :

• doit être de même type que le nœud portant la facette énumération.
• doit être multiple (maxOccurs="unbounded").

Exemple :

Contrainte d'intégrité (Table)

Une référence à une clé primaire de table est définie par une facette étendue tableRef. L'élément doit être du type xs:string.

Element	Description	Obligatoire
container	référence de l'instance qui contient la table.	Non, si cet élément n'est pas spécifié, l'instance est celle contenant la table.
tablePath	Expression XPath qui spécifie la table.	Oui.
labelPaths	Expressions XPath qui spécifient la composition du libellé.	Non, le libellé par défault est la clé primaire.
displayKey	"true" ou "false", spécifie si la clé primaire est affichée en préfixe du libellé.	Non, la valeur par défault est "true".

L'exemple ci-dessous spécifie une référence (clé étrangère) vers une occurence de l'élément 'catalog'.

La facette tableRef est interprétée comme une énumération. La clé étrangère formattée est la valeur de l'élément (type xs:string). Le libellé peut être composé en ajoutant les chemins d'autres champs des occurrences référencées par l'élément labelPaths (les chemins sont absolus dans le contexte de l'occurrence).

 

Facettes programmatiques

webMethods MDM propose d'implémenter des contraintes qui ne sont ni spécifiées par XML Schema, ni proposées en extension par webMethods MDM, via une simple déclaration de classe Java dans le schéma.

Afin de conserver la conformité du document par rapport à la norme XML Schema, ces facettes sont définies sous l’élément

annotation/appinfo/otherFacets.

Contraintes programmatiques

Une facette programmatique est définie par une classe Java implémentant l'interface Java com.softwareag.mdm.schema.Constraint.

Il est possible d'associer des paramètres à la facette. Par conséquent, la classe java implémentée doit être conforme au protocole JavaBean. Dans l'exemple ci-dessous, elle doit définir les méthodes : getParam1(), setParam1(String), ..., getParamX(), setParamX(String), etc.

Exemple :

Contraintes programmatiques de type Enumération

Une contrainte énumération ajoute à une contrainte programmatique basique la définition d'une liste ordonnée de valeurs. Pour cela, on définit une classe Java implémentant l'interface com.softwareag.mdm.schema.ConstraintEnumeration. Cette facette permet la sélection d'une valeur dans une liste.

Exemple :

Contraintes programmatiques de type Nomenclature

Une contrainte nomenclature ajoute à une contrainte programmatique basique la définition d'une liste ordonnée de "valeurs-labels". Pour cela, on définit une classe Java implémentant l'interface com.softwareag.mdm.schema.ConstraintNomenclature. Cette facette permet la sélection d'une valeur dans une liste.

Notons qu'une contrainte énumération (décrite précédemment) est davantage appropriée lorsque l'on souhaite afficher des "valeurs localisées" ou lorsque le nombre d'éléments de la liste de sélection est important.

Exemple :

Contrainte sur valeur nulle

Une contrainte n'est pas vérifiée lorsque la valeur du noeud est nulle. Il est toutefois possible de modifier ce comportement en définissant une contrainte qui implémente l'interface Java com.softwareag.mdm.schema.ConstraintOnNull.

Une contrainte sur valeur nulle n'est applicable qu'à un noeud optionnel avec les attributs suivants : minOccurs="0" et maxOccurs="1".

Un tel contrôle n'est pas exécuté lorsque l'utilisateur spécifie une valeur nulle via l'outil Manager, mais à la validation globale de l'adaptation. Pour spécifier le contrôle à la saisie utilisateur, l'élément doit définir l'attribut mdm:checkNullInput="true".

Exemple :

 

 

Triggers et fonctions

Valeurs calculées

Par défaut, les valeurs des nœuds d’une adaptation sont lues et persistées dans le référentiel MDM. Néanmoins, il est possible d’alimenter la valeur d’un nœud d’adaptation de manière spécifique.

Par exemple, une valeur peut provenir d’un système de persistance externe (base de données relationnelle, système central, etc.). Elle peut aussi être le résultat d'un calcul. Ce calcul (ou l'accès à la base) peut même prendre en compte des paramètres de l'adaptation courante.

Ceci est rendu possible par l’utilisation d’une fonction.

Une fonction est spécifiée dans le schéma XML au moyen de l’élément mdm:function (voir exemple ci-dessous).

• La valeur de l'attribut class doit être le nom qualifié d’une classe Java qui implémente l’interface Java com.softwareag.mdm.adaptation.ValueFunction.
• Des paramètres additionnels peuvent être spécifiés au niveau du schéma, en ce cas la convention des propriétés JavaBean est utilisée.

Exemple: