Ant Integration

2021-05-07

1. Usage

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>

2. Installing a schema

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:

Table 1. Install schema
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:

The following nested elements are supported:

To define where the schema is located you add a nested schema element.

To define how to connect to the database you add one of the server or database nested elements.

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="" />
    <javahome location="C:/apps/jdk/6u45" />
    <memory size="small" />
  </database>
</schema:install>

3. Creating an installation script

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:

Table 2. Installation script
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 how to connect to the database you add one of the server or database nested elements.

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="" />
    <javahome location="C:/apps/jdk/6u45" />
    <memory size="small" />
  </database>
</schema:create-install-script>

4. Exporting a schema

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 how to connect to the database you add one of the server or database nested elements.

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 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="" />
    <javahome location="C:/apps/jdk/6u45" />
    <memory size="small" />
  </database>
</schema:export>

5. Comparing schemas

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.

6. Elements

This section describes elements that can be nested inside the Ant tasks.

6.1. Schema

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

6.2. Server

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:

6.3. Database

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.

6.4. User

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

6.5. Classpath

The <classpath /> element is used to define the classpath to use when connecting in server mode. The classpath should contain the eMatrixServletRMI.jar file. The element supports all the same attributes and nested elements as standard Ant path elements.

6.6. JavaHome

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

6.7. Memory

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', or 'xlarge'. The default value is 'small'.

Enovia HEAP Size

small = 450m

medium = 640m

large = 640m

xlarge = 4096m

Yes

6.8. Parameter

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

6.9. Output

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

6.10. Ignore

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.

6.11. Source

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:

6.12. ModifiedAfter

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

6.13. Filter

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.

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

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>

6.14. Command

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

6.15. Href

The <href /> element is used to define a href to emxTable.jsp to be converted. It supports the following attributes:

Attribute Description Required

href

A URL or href to emxTable.jsp that should be converted to TVC.

Yes

name

The name of the generated page config, etc.

Yes

7. Parameterized Schema Definitions

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>

8. Examples

This section contains example build files.

8.1. Connect to Server

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>

8.2. Connect to Database

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>

8.3. Connect to DB2 Database

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>

8.4. Compare

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>

9. Modularization

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>

10. Troubleshooting

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