The configuration contract XML document is specified using the tags and attributes described in the following tables and sections.

The tables list all the tags and attributes available when writing the configuration contract. It also indicates whether these are optional or required.

Name	Attribute(s)	May occur in	Required

Name	Attribute(s)	May occur in	Required
contract	object-version	-	Yes (exactly 1)
class-name	-	contract	Yes (exactly 1)
package-name	-	contract	Yes (exactly 1)
storable-id	-	contract	Yes (exactly 1)
delegate	id	contract	No (exactly 1)
upgradable-delegate	-	delegate	No (exactly 1)
field	active, hidden, id, level, since	section	Yes (min 1)
title	-	field	Yes (exactly 1)
name	-	field	Yes (exactly 1)
description	-	field	Yes (max 1)
type	-	field	Yes (exactly 1)
primitive-type	name	type, list-of, array-of, map-of, set-of	No (max 1)
object-type	name	type, list-of, array-of, map-of, set-of	No (max 1)
enum-type	name	type, list-of, array-of, map-of, set-of	No (max 1)
password-type	-	type, list-of, array-of, map-of, set-of	No (max 1)
drstorable-type	name, profileType	type, list-of, array-of, map-of, set-of	No (max 1)
drdate-type	-	type, list-of, array-of, map-of, set-of	No (max 1)
list-of	-	type	No (max 1)
array-of	-	type	No (max 1)
set-of	-	type	No (max 1)
default-value	-	field	Yes (max 1)
null-value	-	field	Yes (max 1)
allow-null	-	field	Yes (max 1)
tooltip	-	field	Yes (max 1)
validation	-	field	Yes (max 1)
validate	minLength, maxLength, minValue, maxValue, isValidRegExp, isValidTZ, notNull, matchRegexp, negateRegexp, matchValue, message	validation	No (unlimited)

These are the available attributes:

Name	May occur in	Required

Name	May occur in	Required
object-version	contract	Yes
id	field, section, delegate	Yes
active	field	No
hidden	field	No
level	field	No
since	field	No
minLength	validate	No
maxLength	validate	No
minValue	validate	No
maxValue	validate	No
isValidRegExp	validate	No
isValidTZ	validate	No
notNull	validate	No
matchRegexp	validate	No
negateRegexp	validate	No
matchValue	validate	No
message	validate	Yes
name	primitive-type, object-type, enum-type, drstorable-type	Yes
profileType	drstorable-type	No

contract

The configuration contract starts with a contract declaration. The contract tags should enclose all other tags.

Syntax:

<contract object-version='1.0'>

The object-version attribute specifies the configuration version that this contract was designed for.

Note!
The mz-version attribute for contract is deprecated and has been replaced with the object-version attribute. However, to enable backward compatibility, the mz-version attribute will still work.

class-name

This tag specifies the name of the the Java class that should be generated, and is part of the header in the configuration contract.

Syntax:

<class-name>DiskCollectionConfig</class-name>

package-name

This tag specifies the package name of the the Java class that should be generated, and is part of the header in the configuration contract.

Syntax:

<package-name>com.digitalroute.diskcollection</package-name>

The package name will determine in which directory you must be located when creating the *.jar file as described in Creating a DTK Plugin | Creating a User Defined Jar. With the package name stated in the syntax above, you will have to be where the /com/digitalroute/diskcollection/ directory is located when creating the *.jar file.

storable-id

When specified, the storable-id will be used instead of the classname in exported configurations, and when configurations are persisted to the database. As a result of this, the class can be moved or renamed without breaking existing configurations. This tag is part of the header in the configuration contract.

Syntax:

<storable-id>Prefix.DiskCollectionConfig</storable-id>

Suggested prefix is the company name or similar.

delegate

The delegate tag is a place holder for various types of sub delegate tags, which are used for triggering specific functions defined in the stated Java class. All sub delegate tags must be enclosed by the main delegate tags, which are part of the header in the configuration contract.

Syntax:

<delegate id='com.companyname.myagent.AgentDelegate'>
      <upgradable-delegate/>
</delegate>

The delegate tag has the following attributes:

Attribute	Description

Attribute	Description
`id`	The Java class called when the delegate is triggered. This Java class must implement the Java interface for the delegate.

upgradable-delegate

The upgradable-delegate is used for handling upgrades in configuration contracts If the upgradable-delegate tag is included, the Java class stated as id in the main delegate tag is called when the mzsh upgradeconfig command, or the mzsh systemimport with the -u|-upgrade flag, is used.

The upgradeable-delegate tag must be enclosed by delegate tags, and the delegate class must implement java interface UpgradableDelegate.

Syntax:

<upgradable-delegate>

In the class called you can configure the changes to be made, e g if a field has been changed, added, or renamed, or if types have been changed.

Example - Upgrade procedure

This is an example of how an upgrade procedure may be performed:

In the configuration contract for Agent Z, some fields have been changed in version Y.
A new Java class is needed to implement the UpgradeDelegate interface. This interface is then used as ID in the <delegate>...</delegate> section in the configuration contract, i e agentz.Delegate.java.
In the configuration contract for Agent Z a <delegate>...</delegate> section is added with the ID agentzDelegate.java and containing an <upgradable-delegate> tag.
The configuration contract is sent to the Contract Tool which generates a new Java file that should be compiled. The resulting package should be committed using pcommit.
By running the mzsh upgradeconfig command, the configurations containing this agent will be upgraded with the changes and information about the upgrade will be stored in a an upgrader-log.

section

The section tag specifies a logical grouping of a number of fields that may be configured in the the agent's configuration dialog.

Syntax:

<section id='Disk Collection'/>

The id attribute is the identifier for the section.

field

The field tag is the heart of the configuration contract. Each field tag defines a piece of data that can be configured for the agent, and encloses all of the field related tags.

Syntax:

<field id='directory' level='any' active='true'/>
    <title>Directory</title>
    <name>Directory</name>
    <type> ... </type>
    </field>

The field tag has the following attributes:

Attribute	Description

Attribute	Description
`active`	The `active` attribute is optional. It is used if the field should be disabled by default by setting the value to 'false'. The default value is 'true'.
`hidden`	The `hidden` attribute is optional. It is used if the field should not be shown in Workflow Properties to be made available into the Workflow Table. This is done by setting the value to 'true'. The default value is 'false'.
`id`	The `id` attribute is mandatory and must be unique within the configuration contract.
`level`	The `level` attribute is optional. It defines if the field can be configured in the template, workflow or both. The default value is `any`. The level attribute can have one of the following values: `any` - The value can be configured on both workflow and template level. `instance` - The value can only be configured on workflow level. `template` - The value can only be configured on template level.
`since`	The `since` attribute is optional. It is used to specify at what version of the contract the field was introduced. This makes it possible to manage backward compatibility, so that a new version of the contract can read a previous version.

title

The title tag identifies the field in the GUI, and should be enclosed by the field tags.

Syntax:

<title>Directory</title>

name

The name tag identifies a field when the object is serialized. The value must therefore be unique within the contract document. This tag should be enclosed by the field tags.

Syntax:

<name>Directory</name>

description

The description tag defines a descriptive text for the field, and should be enclosed by the field tags. The value is currently not used.

Syntax:

<description>The source directory</description>

type

Types are described using a small language which represents the different types. The type tags should be enclosed by the field tags.

The following types are supported:

primitive-type
object-type
enum-type
password-type
drstorable-type
drdate-type

Syntax:

<type>specific type</type>

Example - Primitive int type

<type> 
    <primitive-type name='int'/> 
</type>

Example - Type indicating a List of String objects

<type> 
    <list-of> 
        <object-type name='java.lang.String'/> 
    </list-of> 
</type>

primitive-type

The primitive-type tag allows the specification of a field with a primitive Java type.

The following types are supported by this tag:

boolean
byte
char
double
float
int
long
short

Syntax:

<primitive-type name='int'/>

The name attribute is the name of the primitive type.

object-type

The object-type tag allows the specification of supported Java object fields.

The following types are supported by this tag:

java.lang.String
java.math.BigInteger

Syntax:

<object-type name='java.lang.String'/>

The name attribute must be a fully qualified name.

enum-type

The enum-type tag allows the specification of enum fields. Any Java Enum type can be specified.

Syntax:

<enum-type name='enum-type-name'/>

The name attribute must be a fully qualified name.

password-type

The password-type tag allows the specification of encrypted password fields.

Syntax:

<password-type/>

drstorable-type

The drstorable-type tag allows the specification of fields implementing the DRStorable interface.

Syntax:

<drstorable-type name='drstorable-type-name'/>

The name attribute must be a fully qualified name.

array-of

The array-of tag allows the specification of a field containing an array of another type.

Syntax:

<array-of>contained-type-declaration</array-of>

list-of

The list-of tag allows the specification of a field containing a List of another type.

Syntax:

<list-of>contained-type-declaration</list-of>

set-of

The set-of tag allows the specification of a field containing a Set of another type.

Syntax:

<set-of>contained-type-declaration</set-of>

default-value

The default-value tag allows the specification of a default value for a field.

Syntax:

<default-value>"value"</default-value>

tooltip

If the tooltip tag is present, the enclosing field should be included in the tooltip for the agent. The value of the tooltip tag usually contains the title of the field.

Syntax:

<tooltip>"Port"</tooltip>

validation

The validation tag is the start tag for the specification of validation rules. The validation element can contain several validation rules.

Example - Validation of a String

<validation> 
  <validate minLength='1' message='The value is too short'> 
  <validate maxLength='10' message='The value is too long'> 
</validation>

validate

Specifies a validation rule, and should be enclosed by the validation tags.

Syntax:

<validate 'rule' = 'value' message='error message'

Where rule can be one of the following:

Rule	Description

Rule	Description
`minValue`	Checks if the value is greater than or equal to the min value.
`maxValue`	Checks if the value is less than or equal to the max value.
`minLength`	Checks if the value's adjusted length is greater than or equal to the min length.
`maxLength`	Checks if the value's length is less than or equal to the max length.
`isValidRegExp`	Checks if the value is a valid regular expression.
`matchRegexp`	Checks if the value matches the specified regular expression.

Example - Validation Rules for a TCP port

<validate minValue='0' maxValue='65535' message='Port number is not valid'/>

Configuration Contract Tags

contract

class-name

package-name

storable-id

delegate

upgradable-delegate

section

field

title

name

description

type

primitive-type

object-type

enum-type

password-type

drstorable-type

array-of

list-of

set-of

default-value

tooltip

validation

validate