2024-12-13
To use the Ant tasks you need access to the Schema Tool JAR. Then you have to import the Ant tasks into your project.
<project xmlns:schema="urn:schematool">
<path id="schematool.classpath">
<fileset dir="lib/schematool" includes="*.jar"/>
</path>
<taskdef uri="urn:schematool"
resource="com/technia/tools/schema/ant/antlib.xml"
classpathref="schematool.classpath" />
</project>The install task can be used to install a schema into a database. It will read the schema in the specified location and make the necessary changes in the database. This task supports the following attributes:
| Attribute | Description | Required |
|---|---|---|
readonlyattributes |
A comma-separated list of attribute names whose values should NOT be updated/modified when installing. Symbolic names are NOT allowed. The default attribute names are: eService Next Number and TVC Number. |
No |
The following nested elements are supported:
To define where the schema is located you add a nested schema element.
To define that only items in files modified after a certain date should be installed you add the optional modifiedafter element.
For example, the following definition will connect to ENOVIA as 'creator' via a web server at localhost listening to port 8080. It expects to find the eMatrixServletRMI.jar file in the lib directory. It also specifies that an alternate JDK should be used while installing the schema. Note that the <javahome /> and <memory /> elements are optional.
<schema:install>
<schema location="schema" parameterfile="config/params.properties" />
<server host="http://localhost:8080/enovia">
<user name="creator" password="" />
<classpath>
<pathelement location="lib/eMatrixServletRMI.jar" />
</classpath>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</server>
</schema:install>The following example will directly connect to the ENOVIA database using the specified ENOVIA server installation and bootstrap file. Note that the <javahome /> and <memory /> elements are optional.
<schema:install>
<schema location="schema" />
<database enoviahome="C:/apps/enovia/V6R2010x/server" bootstrap="boots/MATRIX-R">
<user name="creator" password="" encrypted="false"/>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</database>
</schema:install>In addition to directly installing a schema, you can also use the Schema Tool to create an MQL installation script for later use. For this you use a task called create-install-script. This task works exactly like the install task, except it will not update the database; instead it will write all MQL commands to a local file. It supports the following attributes:
| Attribute | Description | Required |
|---|---|---|
readonlyattributes |
A comma-separated list of attribute names whose values should NOT be updated/modified when installing. Symbolic names are NOT allowed. The default attribute names are: eService Next Number and TVC Number. |
No |
The following nested elements are supported:
To define where the schema is located you add a nested schema element.
To define that only items in files modified after a certain date should be installed you add the optional modifiedafter element.
For example, the following definition will connect to ENOVIA as 'creator' via a web server at localhost listening to port 8080. It expects to find the eMatrixServletRMI.jar file in the lib directory. It also specifies that an alternate JDK should be used while installing the schema. Note that the <javahome /> and <memory /> elements are optional.
<schema:create-install-script>
<schema location="schema" />
<output location="install.mql" />
<server host="http://localhost:8080/enovia">
<user name="creator" password="" />
<classpath>
<pathelement location="lib/eMatrixServletRMI.jar" />
</classpath>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</server>
</schema:create-install-script>The following example will directly connect to the ENOVIA database using the specified ENOVIA server installation and bootstrap file. Note that the <javahome /> and <memory /> elements are optional.
<schema:create-install-script>
<schema location="schema" />
<output location="install.mql" />
<database enoviahome="C:/apps/enovia/V6R2010x/server" bootstrap="boots/MATRIX-R">
<user name="creator" password="" encrypted="false"/>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</database>
</schema:create-install-script>The export task extracts a schema from a database. It will examine the schema at the specified location (if any), compare it against the database and export all differences as definitions (i.e., an XML file will only be overwritten if the definition doesn’t match the corresponding object in the database).
The following nested elements are supported:
To define where the schema is located you add a nested schema element. The path should point to a folder into which you want the schema to be exported. If the path doesn’t exist it will be created.
To define that only items modified after a certain date should be exported you add the optional modifiedafter element.
To filter which items should be exported you add the optional filter element.
To define which items should not be exported, you add the optional exclude element.
To further customize the export behavior you can add the optional ignore element.
<schema:export>
<schema location="schema" />
<server host="http://localhost:8080/enovia">
<user name="creator" password="" />
<classpath>
<pathelement location="lib/eMatrixServletRMI.jar" />
</classpath>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</server>
</schema:export>The following example will directly connect to the ENOVIA database using the specified ENOVIA server installation and bootstrap file. Note that the <javahome /> and <memory /> elements are optional.
<schema:export>
<schema location="schema" />
<database enoviahome="C:/apps/enovia/V6R2010x/server" bootstrap="boots/MATRIX-R">
<user name="creator" password="" encrypted="false"/>
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</database>
</schema:export>You can compare up to five schemas against each other using the compare task. The output from this task is a static report in the form of HTML pages.
The following nested elements are supported:
The following example compares three schemas. The generated report will be written to the build/report folder.
<schema:compare>
<output location="build/report" />
<source title="Current Version">
<schema location="schemas/current" />
</source>
<source title="OOTB Old Version">
<schema location="schemas/ootb-old" />
</source>
<source title="OOTB New Version">
<schema location="schemas/ootb-new" />
</source>
</schema:compare>| This task can at the time of writing only compare tables, forms and policies. |
This section describes elements that can be nested inside the Ant tasks.
The <schema /> element specifies where an XML schema is located. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
location |
The path to the folder that contains the schema, i.e., the folder that contains the schema.xml file. If you’re exporting a schema to this location the folder doesn’t have to exist (it will be created if necessary). |
Yes |
The <server /> element specifies how to connect to an ENOVIA server (RMI or HTTP). It supports the following attributes:
| Attribute | Description | Required |
|---|---|---|
host |
The host of the ENOVIA server. For example, if you’re connecting to the web application server you might define the host as: http://localhost:8080/enovia |
Yes |
The following nested elements are supported:
The <database /> element defined how to directly connect to an ENOVIA database. It supports the following attributes:
| Attribute | Description | Required |
|---|---|---|
bootstrap |
The path to the bootstrap file, i.e., the MATRIX-R file that contains the information required by ENOVIA to connect to the database. |
Yes |
enoviahome |
The path to the folder where the ENOVIA Live Collaboration Server is installed. |
Yes |
The following nested elements are supported:
Backup INI Files If They’re Important
Note that when you connect directly to the database, the Schema Tool will overwrite the %windir%\eMatrix.ini file on Windows for ENOVIA V6R2010 or earlier. If you use the MQL connection mode it will also overwrite the MATRIX.INI file. Therefore, if your setup depends on these files (i.e., if you don’t use a bootstrap manager), you should consider to backup and restore these files before and after running the Schema Tool; for instance using the standard <copy /> task in Ant for copying files.
|
The <user /> element is used to configure the name of the user to login as when connecting to ENOVIA. Note that this user must be a system administrator, e.g., creator. It supports the following attributes:
| Attribute | Description | Required |
|---|---|---|
name |
The name of the ENOVIA user that the tool should connect as to export or install a schema. This user must be a system administrator, e.g., creator. |
Yes |
password |
The password for the ENOVIA user (see above). |
Yes |
The <javahome /> element is used to configure which JDK to use when launching the background process that executes the requested task. By default it will use the current JDK (that you run Ant with). It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
location |
The path to where the JDK has been installed. Note that this should point to the installation folder (as the JAVA_HOME env does) and not to the actual executable. |
Yes |
The <memory /> element is optional and can be used to configure the ENOVIA memory settings. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
size |
Defines the amount of memory to allocate, the value should be either 'small', 'medium', 'large', 'xlarge' or 'xxlarge'. The default value is 'small'. Enovia HEAP Size small = 450m medium = 640m large = 640m xlarge = 4096m xxlarge = 6144m |
Yes |
The <parameter /> element can be used to configure ENOVIA workspace parameters when the database connection option is used. (The kind of parameters you set in enovia.ini or mxEnv.sh.) The following attributes are required:
| Attribute | Description | Required |
|---|---|---|
name |
The name of the parameter. E.g., DB2CODEPAGE, DB2DIR, DB2INSTANCE. Note that you typically do not need to provide additional parameters since the Schema Tool will generate them based on the information you’ve given it. However, if you are connecting to a DB2 database you need to provide the parameters listed above (either using this element or as system environment variables). |
Yes |
value |
The parameter’s value. |
Yes |
The <output /> element specifies where the generated file or files will be written. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
location |
Defines the file or folder where the generated file will be written. Whether the path should point to a file or folder depends on the task that you nest this element within. |
Yes |
The <ignore /> element can be used to configure how a schema is exported. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
enoviaproperties |
A boolean value that defines whether standard ENOVIA properties will be exported or not. These properties include 'installer', 'version', etc. Note that these properties will NOT be exported by default. |
No |
| Exporting Standard ENOVIA Properties While Upgrading Upon installing a schema the tool will add or overwrite standard ENOVIA properties if (and only if) they are present in the XML files. I.e., the tool will never remove these properties from the database when they’re not in the XML files. The idea is that, since these properties aren’t important for the schema itself (only for the ENOVIA Schema Installer), you shouldn’t have to keep track of these properties in your schema definition files. However, it can be useful to export these properties when upgrading from one ENOVIA schema version to another using the Schema Tool. Exporting a schema with these properties means that you will be able to compare and transfer these properties from one database to another with the Schema Tool. |
The <source /> element is used to define a source schema when creating a report. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
title |
The name of the schema (as it will appear in the report). This is a required attribute and the value can be any text that you want to use to identify a schema in a report. |
Yes |
The following nested elements are supported:
The <modifiedafter /> element is used to define that only items modified after a certain date will be installed or exported.
| Attribute | Description | Required |
|---|---|---|
date |
If set, only items that have been modified after the specified date will be installed or exported. The following formats are accepted: MM/dd/yyyy hh:mm:ss aa MM/dd/yyyy hh:mm aa MM/dd/yyyy yyyy-MM-dd HH:mm:ss yyyy-MM-dd HH:mm yyyy-MM-dd |
Yes |
The <filter /> element is used to filter which items will be exported from the database. If you don’t explicitly define a filter while exporting a default filter will be used that exports all supported admin objects, all filters on the role "Global User" (if it exists), and all business objects and connections in the vaults "eService Administration" and "TVC Administration" (if they exist). By adding a filter element to the export definition you can define exactly which items will be exported by supplying name patterns, and where appropriate other relevant information.
The <exclude /> element is used to specify which items will not be exported from the database. It can be used in addition to the <filter /> element.
To filter which items to include you add one or more of the following elements:
association
attribute
businessobject
channel
command
dimension
expression
filter
form
format
group
inquiry
interface
location
menu
page
person
policy
portal
program
relationship
resource
role
rule
site
store
table
type
vault
pathtype
package
|
The following Admin types are not supported by Schematool operations
|
The following attributes are supported by these elements:
| Attribute | Description | Required for Elements |
|---|---|---|
pattern |
The name pattern that applies to the particular type of object. |
all |
typepattern |
The type pattern to apply when querying for business objects. |
businessobject |
user |
The name of the user that owns the workspace object. |
filter |
vault |
The name of the vault in which to query for business objects and connections. |
businessobject |
For example, the following definition will export all commands whose name starts with "TVC" or "FAO", all programs, all filters on "Global User" whose name contains "From" and all business objects in "TVC Administration" whose type name contains "Page" and whose name contains "Navigate".
<schema:export>
<schema location="schema" />
<filter>
<command pattern="TVC*" />
<command pattern="FAO*" />
<program pattern="*" />
<filter user="Global User" pattern="*From*" />
<businessobject vault="TVC Administration" typepattern="*Page*" pattern="*Navigate*" />
</filter>
<database enoviahome="C:/apps/enovia/V6R2010x/server" bootstrap="boots/MATRIX-R">
<user name="creator" password="" />
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</database>
</schema:export>As an other example, the following definition will export all menus, pages, persons, programs or policies but the ones defined in the exclude section.
<schema:export>
<schema location="schema" />
<filter>
<menu pattern="*" />
<page pattern="*" />
<person pattern="*" />
<program pattern="*" />
<policy pattern="*" />
</filter>
<exclude>
<menu pattern="*12*" />
<page pattern="Pe*" />
<person pattern="ad*" />
<program pattern="pr*" />
<policy pattern="p*" />
</exclude>
<database enoviahome="C:/apps/enovia/V6R2010x/server" bootstrap="boots/MATRIX-R">
<user name="creator" password="" />
<javahome location="C:/apps/jdk/6u45" />
<memory size="small" />
</database>
</schema:export>The <command /> element is used to define the name of a command to be converted. It supports the following attribute:
| Attribute | Description | Required |
|---|---|---|
command |
The name of the command that you want to convert, or a regular expression. If you specify a regular expression the task will convert all emxTable.jsp commands whose name match the regular expression. To pass a regular expression instead of a command name you have to prefix it with regex:. |
Yes |
Some schema definitions may contain environment specific values. As of 2015.1.0 it is possible to parameterize these and resolve the parameter against a provided set of parameters.
The definitions / properties that allow parameterization are listed below:
Location
protocol
host
port
path
user
password
searchURL
fcsURL
Store
protocol
host
port
path
user
password
tableSpace
indexSpace
searchURL
fcsURL
vault
Vault
tablespace
indexspace
server
A parameter is defined as:
@{name_of_param}Example
<definition>
<store>
<id>store_MyStore</id>
<host>@{store_MyStore.host}</host>
...
</store>
</definition>The schema element in the ant file supports configuring either to use an external properties file for parameter substitution or define the parameters inline. Example below:
<schema location="schema" parameterfile="config/params.properties">
<param name="store_MyStore.host" value="localhost" />
<param name="..." value="..." />
</schema>This section contains example build files.
This build file connects to the ENOVIA database via a web server. Note that you can use same approach to connect to an RMI server.
<project xmlns:schema="urn:schematool">
<path id="schematool.classpath">
<fileset dir="lib/schematool" includes="*.jar" />
</path>
<taskdef uri="urn:schematool"
resource="com/technia/tools/schema/ant/antlib.xml"
classpathref="schematool.classpath" />
<property name="schema.dir" value="schema" />
<property name="enovia.server.host" value="http://localhost:8080/ematrix" />
<property name="enovia.server.api" value="lib/eMatrixServletRMI.jar" />
<property name="enovia.user" value="creator" />
<property name="enovia.password" value="" />
<property name="install.script" value="install.mql" />
<property name="alt.jdk.home" value="C:/apps/jdk/6u45" />
<property name="memory.size" value="small" />
<target name="schema.install">
<schema:install>
<schema location="${schema.dir}" />
<server host="${enovia.server.host}">
<user name="${enovia.user}" password="${enovia.password}" />
<classpath>
<pathelement location="${enovia.server.api}" />
</classpath>
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</server>
</schema:install>
</target>
<target name="schema.installscript">
<schema:create-install-script>
<output location="${install.script}" />
<schema location="${schema.dir}" />
<server host="${enovia.server.host}">
<user name="${enovia.user}" password="${enovia.password}" />
<classpath>
<pathelement location="${enovia.server.api}" />
</classpath>
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</server>
</schema:create-install-script>
</target>
<target name="schema.export">
<schema:export>
<schema location="${schema.dir}" />
<server host="${enovia.server.host}">
<user name="${enovia.user}" password="${enovia.password}" />
<classpath>
<pathelement location="${enovia.server.api}" />
</classpath>
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</server>
</schema:export>
</target>
</project>This build file connects directly to the ENOVIA database.
<project xmlns:schema="urn:schematool">
<path id="schematool.classpath">
<fileset dir="lib/schematool" includes="*.jar" />
</path>
<taskdef uri="urn:schematool"
resource="com/technia/tools/schema/ant/antlib.xml"
classpathref="schematool.classpath" />
<property name="schema.dir" value="schema" />
<property name="enovia.bootstrap" value="boot/MATRIX-R" />
<property name="enovia.server.home" value="C:/apps/enovia/V6R2010x/server" />
<property name="enovia.user" value="creator" />
<property name="enovia.password" value="" />
<property name="install.script" value="install.mql" />
<property name="alt.jdk.home" value="C:/apps/jdk/6u45" />
<property name="memory.size" value="small" />
<target name="schema.install">
<schema:install>
<schema location="${schema.dir}" />
<database enoviahome="${enovia.server.home}" bootstrap="${enovia.bootstrap}">
<user name="${enovia.user}" password="${enovia.password}" />
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</database>
</schema:install>
</target>
<target name="schema.installscript">
<schema:create-install-script>
<output location="${install.script}" />
<schema location="${schema.dir}" />
<database enoviahome="${enovia.server.home}" bootstrap="${enovia.bootstrap}">
<user name="${enovia.user}" password="${enovia.password}" />
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</database>
</schema:create-install-script>
</target>
<target name="schema.export">
<schema:export>
<schema location="${schema.dir}" />
<database enoviahome="${enovia.server.home}" bootstrap="${enovia.bootstrap}">
<user name="${enovia.user}" password="${enovia.password}" />
<javahome location="${alt.jdk.home}" />
<memory size="${memory.size}" />
</database>
</schema:export>
</target>
</project>This build file connects directly to the ENOVIA database with extra parameters required for DB2.
<?xml version="1.0"?>
<project xmlns:schema="urn:schema" default="install">
<path id="libs">
<fileset dir="lib" includes="*.jar" />
</path>
<taskdef uri="urn:schema" resource="com/technia/tools/schema/ant/antlib.xml" classpathref="libs" />
<property name="enovia.java" value="/usr/jdk/6u45" />
<property name="enovia.home" value="/enovia2013x/server" />
<property name="enovia.bootstrap" value="${enovia.home}/MATRIX-R" />
<property name="db2.codepage" value="1208" />
<property name="db2.dir" value="/opt/IBM/db2/V9.7" />
<property name="db2.instance" value="plm" />
<property name="username" value="creator" />
<property name="password" value="secret" />
<target name="install">
<schema:install>
<schema location="schema" />
<database enoviahome="${enovia.home}" bootstrap="${enovia.bootstrap}">
<user name="${username}" password="${password}" />
<javahome location="${enovia.java}" />
<parameter name="DB2CODEPAGE" value="${db2.codepage}" />
<parameter name="DB2DIR" value="${db2.dir}" />
<parameter name="DB2INSTANCE" value="${db2.instance}" />
</database>
</schema:install>
</target>
<target name="export">
<schema:export>
<schema location="build/schema" />
<filter>
<attribute pattern="*" />
</filter>
<database enoviahome="${enovia.home}" bootstrap="${enovia.bootstrap}">
<user name="${username}" password="${password}" />
<javahome location="${enovia.java}" />
<parameter name="DB2CODEPAGE" value="${db2.codepage}" />
<parameter name="DB2DIR" value="${db2.dir}" />
<parameter name="DB2INSTANCE" value="${db2.instance}" />
</database>
</schema:export>
</target>
</project>The following example shows you how to compare multiple schemas. While this example only compares three schemas, you can compare up to five schemas at a time.
<project xmlns:schema="urn:schematool">
<path id="schematool.classpath">
<fileset dir="lib/schematool" includes="*.jar" />
</path>
<taskdef uri="urn:schematool"
resource="com/technia/tools/schema/ant/antlib.xml"
classpathref="schematool.classpath" />
<target name="schema.compare">
<schema:compare>
<output location="build/report" />
<source title="Current Version">
<schema location="schemas/current" />
</source>
<source title="OOTB Old Version">
<schema location="schemas/ootb-old" />
</source>
<source title="OOTB New Version">
<schema location="schemas/ootb-new" />
</source>
</schema:compare>
</target>
</project>There is support for dividing a schema into multiple schemas. The below snippet should be placed in a schema.xml file that is placed in the root of the schema (src/main/schema).
In this example there are two modules (folders) 1 and 2 (they can be named as you see fit), that have been created beneath another folder called modules. A schema can also have a name. Beneath folders 1 and 2 there must be a schema.xml as there usually is.
<?xml version="1.0" ?>
<schema>
<dependencies>
<schema name="One" src="modules/1" />
<schema name="Two" src="modules/2" />
</dependencies>
</schema>If you want Ant to output more details about what the tool is doing, such as when you get an error, you can use Ant’s -d or -v command line switch to enable debug or verbose output respectively (note that the debug switch will print all information that verbose prints and more). E.g., when the schema tool runs with verbose output enabled it will print all the MQL commands that it’s executing or all files that it’s parsing.
ant -d schema.install