CTT ANT Task Reference

 

Content

Overview

ExportXML

Connection

SDI

WebPage

SDC

Table
 
Column

Data

SDIDetail

PropertyTree

Node

TransferPackage

ImportXML

 

Overview

Top ../images/arwup.gif (846 bytes)

General Information

This is a reference guide for ANT Tasks used with the Configuration Transfer Tools (CTT). Before using ANT Tasks, acquire a thorough familiarity with ANT and the CTT. This information makes numerous references to CTT terminology.

For complete documentation concerning ANT, visit http://ant.apache.org/manual/index.html.

Run ANT from within LabVantage by going to System Admin - System Tools - Run Ant.

In addition to the examples provided with each task, see CTT Export Example for a demonstration of the overall file structure.

 

ExportXML

Top ../images/arwup.gif (846 bytes)

Description

• Defines a group of exports (SDIs, SDCs, Tables, Property Trees) to a common directory or file.
• Must include a Connection task and at least one of these export tasks: SDC, SDI, Table, or PropertyTree.

Attributes

Attribute Description Required
dir Directory for all exports defined within the element. Each export is written to a different file. One of these is required.
file Name of the file to which all exports are written.
zipfile Name of the zip file to which all exports are written.
logimport "logimport" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
esigpassword "esigpassword" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
esigreason "esigreason" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
checksum "checksum" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)

Example

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="User" keyid1="Admin"/>

</exportxml>

 

Connection

Top ../images/arwup.gif (846 bytes)

Description

Specifies how to connect to the source database:

• Use datasource attributes if running within LabVantage.
• Use JDBC attributes (for the relevant DBMS) if running outside of LabVantage.

Attributes

datasource

Attribute Description Required
dbms Single DBMS for the source and target. Yes... required for
JNDI-based connections.
jndiname JNDI name.

JDBC (Oracle DBMS)

Attribute Description Required
server Name of the machine hosting the database. Yes... required for
JDBC-based connections to Oracle DBMS.
port Port on which the database is listening.
sid Oracle SID.
username Login username.
password Login password.

JDBC (MS SQL Server DBMS)

Attribute Description Required
server Name of the machine hosting the database. Yes... required for
JDBC-based connections to MS SQL Server DBMS.
sqldatabase Database name.
username Login username.
password Login password.

Examples

<connection dbms="ORA" jndiname="sapphire"/>

<connection server="myserver" sid="production" port="1521" username="admin" password="admin"/>


SDI

Top ../images/arwup.gif (846 bytes)

Description

• Defines the export of a set of SDIs and their related data.
• Criteria attributes define which SDIs are exported (one of KeyId, Query, Category, or Keyfile).
• Data attributes define what data are exported.
• Import attributes define how to handle the import.
• Can include Column, SDIDetail, and/or Data tasks.

Attributes

Criteria

KeyId
Attribute Description Required
sdcid Identifier of the SDC. Yes
keyid1
keyid2
keyid3 		SDI Keys. Yes... required for keyid-based selection of SDIs.
Query
Attribute Description Required
sdcid Identifier of the SDC. Yes... required for query-based selection of SDIs.
queryfrom From clause.
querywhere Where clause.
queryorderby OrderBy clause.
Category
Attribute Description Required
sdcid Identifier of the SDC. Yes... required for category-based selection of SDIs.
categoryid Identifier of the Category SDI.
Keyfile
Attribute Description Required
sdcid Identifier of the SDC. Yes... required for keyfile-based selection of SDIs.
keyfile Name of the file containing the list of SDIs.
keyseparator Character used to separate (delimit) the SDIs.

Data

Attribute Description Required
exportdetails Export rows from a detail table of the SDI. No (default = true)
exportsdidetails Export rows from the SDIDetail table. No (default = true)
exportfkdetails Export rows linked by foreign key to the SDI. No (default = false)
exportroles Export Roles associated with the SDI. No (default = true)
exportcategories Export Categories associated with the SDI. No (default = true)
excludeauditcolumns Exclude audit columns from the export. No (default = true)
syncdatamodel Synchronize the target with the source. No (default = false)

Import

Attribute Description Required
primaryforceupdate Force update for the SDI. No (default = false)
primaryforceupdatenull Force null for the SDI. No (default = false)
detailforceupdate Force update for the detail of the SDI. No (default = false)
detailforceupdatenull Force null for the detail of the SDI. No (default = false)

Predefined

Attribute Description Required
exportid User-predefined export. This is the value of the "exportid" column in the "SDCExport" table. Predefined exports drive from an RSet that contains the set of KeyIds being exported. This attribute is mutually exclusive with the other data attributes, i.e., the "exportid" takes precedence. There is no default value.

File

Attribute Description Required
file Name of the export file. No (default = [sdcid].xml)

Flush

Attribute Description Required
flushdetails Flush details before they are imported. No (default = false)
flushsdidetails Flush SDI details before they are imported. No (default = false)
flushroles Flush Roles before they are imported. No (default = false)
flushcategories Flush Categories before they are imported. No (default = false)

Export Security Details

Attribute Description Required
Export Security Details Controls whether Security Details are exported. No (default = false)

Examples

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" keyid1="AddSDI" keyid2="1"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" queryfrom="action" querywhere="actionid in ("AddSDI", "DeleteSDI")"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" categoryid="SDIMaintenance"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" keyfile="c:\temp\export\actions.txt"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" categoryid="myproj">

<column columnid="actionid"/>

<column columnid="actiondesc"/>

</sdi>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" categoryid="myproj" exportdetails="false" exportsdidetails="false" exportroles="false" exportcategories="false"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action" categoryid="myproj" primaryforceupdate="true" detailforceupdate="true"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="RefType" keyid1="BoxStatus" exportcategories="true" flushcategories="true" exportroles="true" flushroles="true"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Product" keyid1="Jam" keyid2="Berry"� exportdetails="true" flushdetails="true" exportsdidetails="true" flushsdidetails="true" exportcategories="true" flushcategories="false" exportroles="true" flushroles="false"/>

</exportxml>

Exporting Additional Detail Tables

ANT exports provide a mechanism for including additional detail tables in an SDI export using the <sdidetail/> element. For example:

<sdi sdcid="Project"; keyid1="MyProj" ...>

<sdidetail detailid="sdinote"/>

</sdi>

WebPage

Top ../images/arwup.gif (846 bytes)

Description

Defines the export of a webpage.

Attributes

The WebPage task provides the same attributes as the SDI task, plus these:

Attribute Description Required
exportnodes Include the Web page node data in the export. No (default = true)
forcepageoverrides Overwrite the page overrides on the target. No (default = true)
nodeexists Determines how nodes are imported on the target if they already exist (ignore, merge, or replace). These are the WPD Set Export options in the Configuration Transfer Tools. No (default = replace)
nodepropertyexists Determines how node properties are imported on the target if they already exist (ignore, merge, or replace). These are the WPD Set Export options in the Configuration Transfer Tools. No (default = replace)

 

SDC

Top ../images/arwup.gif (846 bytes)

Description

• Defines the export of a set of SDC definitions and the associated data model.
• Can include Column tasks.
• Can use wildcards for SDCIds to export all SDCs (see the example below).

Attributes

Attribute Description Required
sdcid Identifier of the SDC. Yes
file Name of the export file. No (default = [sdcid].xml)
categoryid Can be used to select SDCs by Category.

This attribute is mutually exclusive with the sdcid attribute, e.g.,

<sdc categoryid="myproject"/>

selects all SDCs marked with the "myproject" Category.

 No (default = false)
excludeauditcolumns Exclude audit columns from the export. See the SDI Export Options in the Configuration Transfer Tools. No (default = true)
excludelinktables Exclude link tables (defined in the SDCLink table) from the export. No (default = false)
flushupdtables Flushes the updXXX tables on the target prior to importing the data model changes. No (default = true)
forceupdate Forces update of column values of data exported to the target. No (default = true)
forcenullupdate Overwrites column values of data exported to the target, but only if the target value is null. No (default = false)
componentcode Directs the export to exclude columns not in the component code provided. No (default = false)

Examples

Export Discrete SDCs

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdc sdcid="Action"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdc sdcid="Action;User"/>

</exportxml>
Export All SDCs

<exportXML file="${export.dir}\sdcwildcard.xml">

<connection server="${sapphire.db.servername}" port="${sapphire.db.port}"

sid="${sapphire.db.sid}" username="${sapphire.db.username}"

password="${sapphire.db.password}"/>

<sdc sdcid="*"/>

</exportXML>

 

Table

Top ../images/arwup.gif (846 bytes)

Description

• Defines the export of data from a table.
• Data for export can be defined by Query, Keyfile, or Datafile attributes.
• Can include Column and/or Data tasks.
• Can take all tables defined in the schema, e.g.,
Oracle:  SELECT table_name FROM user_tables
MS SQLServer:  SELECT name FROM sysobjects WHERE xtype='U'

You can use the from and where attributes to restrict these sets.

Attributes

Query

Attribute Description Required
tableid Identifier of the table. Yes... required for query-based selection of rows.
from From clause.
where Where clause.
orderby OrderBy clause.

Keyfile

Attribute Description Required
tableid Identifier of the table. Yes... required for keyfile-based selection of rows.
keyfile Name of the file containing the list of SDIs.
keyseparator Character used to separate (delimit) the SDIs.

Datafile

Attribute Description Required
tableid Identifier of the table. Yes... required for selection of data from a data file.
datafile Name of the file containing the list of SDIs.

General Attributes

Attribute Description Required
tablealias Alias for the table. No
file Name of the export file. No (default = [tableid].xml)
forcelobexport Forces LOB exports. No (default = false)
verbose Generates verbose export log. No (default = false)
excludeauditcolumns Excludes audit columns. See the SDI Export Options in the Configuration Transfer Tools. No (default = true)

Examples

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action" from="action" where="actionid in ( "AddSDI", "DeleteSDI")"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action" keyfile="c:\temp\export\actions.txt"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action" datafile="c:\temp\export\actiondata.txt"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action">

<column columnid="actionid"/>

<column columnid="actiondesc"/>

</table>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action" excludeauditcolumns="true">

<column columnid="actionid"/>

<column columnid="actiondesc"/>

</table>

</exportxml>


Column

Top ../images/arwup.gif (846 bytes)

Description

• Defines specific requirements of a column export.
• LOB column contents are exported to a separate file.
• Can include PropertyTree tasks.

Attributes

Attribute Description Required
columnid Identifier of the column. Yes
forceupdate Enables Force Update option. See the SDI Export Options in the Configuration Transfer Tools. No (default = false)
forcenullupdate Enables Force Null Update option. See the SDI Export Options in the Configuration Transfer Tools. No (default = false)
value Value of the specified column. No
file Name of the file to which the column value is written.
No (default = [tableid]/[rowkey]_[columnid].xml)
excluded Excludes the specified column. No (default = false)

Examples

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action">

<column columnid="actionid"/>

<column columnid="actiondesc"/>

<column columnid="actiontype" value="S"/>

</table>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="Action">

<column columnid="*"/>

<column columnid="tracelogid" excluded="true"/>

</table>

</exportxml>

 

Data

Top ../images/arwup.gif (846 bytes)

Description

Defines specific data to export for a table, i.e., data is not retrieved from the database.

Attributes

Attribute Description Required
separator Character used to separate (delimit) the data. No

Example

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<table tableid="sysconfig">

<column columnid="propertyid"/>

<column columnid="propertyvalue"/>

<data separator=";">

<![CDATA[ property1;value1_property2;value2 ]>

</data>

</table>

</exportxml>

 

SDIDetail

Top ../images/arwup.gif (846 bytes)

Description

• Defines a specific detail table export for an SDI export.
• Used to override default detail table exports derived from SDI task Data attributes.
• Can include Column and/or Data tasks.
• Can exclude a detail table.

Attributes

Attribute Description Required
detailid Identifier of the detail table. Yes
extendedwhere Extended where clause. No
excluded Excludes a detail table (see the example below). No
flush Flush details before they are imported. No

Example

Export Detail Table

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<sdi sdcid="Action">

<sdidetail detailid="actionproperty"/>

</sdi>

</exportxml>
Exclude Detail Table

<exportXML file="${export.dir}\actionwithoutactionproperty.xml">

<connection server="${sapphire.db.servername}" port="${sapphire.db.port}"

sid="${sapphire.db.sid}" username="${sapphire.db.username}"

password="${sapphire.db.password}"/>

<sdi sdcid="Action" keyid1="AddSDI" keyid2="1">

<sdidetail detailid="actionproperty" excluded="true"/>

</sdi>

</exportXML>

 

PropertyTree

Top ../images/arwup.gif (846 bytes)

Description

• Defines a complete or partial Property Tree export (from the PropertyTree table).
• Can include the Node task.

Attributes

Attribute Description Required
propertytreeid Identifier of the Property Tree. Yes
file Name of export file. No (default = [tableid].xml)
exists Determines how to import the Property Tree on the target if the Property Tree already exists (ignore, merge, or replace). See the WPD Set Export options in the Configuration Transfer Tools. No (default = merge)
notexists Determines how to import the Property Tree on the target if the Property Tree does not exist (ignore or add). See the WPD Set Export options in the Configuration Transfer Tools. No (default = add)

Examples

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<propertytree propertytreeid="maint"/>

</exportxml>

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<propertytree propertytreeid="maint">

<node nodeid="Sample Custom"/>

</propertytree>

</exportxml>

 

Node

Top ../images/arwup.gif (846 bytes)

Description

Defines a set of nodes to export from a Property Tree.

Attributes

Attribute Description Required
nodeid Identifier of the node exported from the Property Tree.

Set this to * to export all nodes.

 Yes, required for nodeid-based selection of nodes.
categoryid Identifier of the Category containing the exported nodes. Yes, required for Category-based selection of nodes.
collapseancestors Whether or not to collapse/merge the ancestor properties into this node export. No (default = false)
includeancestors Whether or not to export ancestor nodes with the specified nodeid. No (default = false)
includedescendants Whether or not to export descendent nodes with the specified nodeid. No (default = false)
exists Determines how the node is imported on the target if the node already exists (ignore, merge, or replace). No (default = merge)
notexists Determines how the node is imported on the target if the node does not exist (ignore or add). No (default = add)

Example

<exportxml dir="c:\temp\export">

<connection dbms="ORA" jndiname="sapphire"/>

<propertytree propertytreeid="maint">

<node nodeid="Sample Custom" includedescendants="true"/>

</propertytree>

</exportxml>

 

TransferPackage

Top ../images/arwup.gif (846 bytes)

Description

• Executes a Transfer Package.
• Transfer Packages can be executed from the database or from a file. The transferpackageid and file attributes are therefore mutually exclusive.

Attributes

Attribute Description Required
transferpackageid User-predefined Transfer Package in the database. Yes... required for execution of a transfer package from the database.
file Name of the user-predefined file containing the Transfer Package. Yes... required for execution of a transfer package from a file.
zipfile Name of the output zip file. No
inheritrefs Whether or not properties from ANT are passed into the Transfer Package. No (default = true)
logimport "logimport" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
esigpassword "esigpassword" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
esigreason "esigreason" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)
checksum "checksum" attribute that is written into the exportpackage header. This attribute is used to control the import of the file (see Importing Items in the Configuration Transfer Tools). No (default = false)

 

ImportXML

Top ../images/arwup.gif (846 bytes)

Description

• Defines a group of imports.
• Must include the Connection task (to specify the target database).
• Must include at least one "fileset" task (to define the set of imported files). The "fileset" task is a standard ANT task with many options for selecting and excluding files (see the ANT documentation).

Attributes

Attribute Description Required
forceupdate Enables the "Force Update" option (see the SDI Export Options in the Configuration Transfer Tools). No (default = false)
ignoremissingobjects Enables the "Ignore Missing Objects" option (see Importing Items in the Configuration Transfer Tools). No (default = false)
regenkeys Enables the "Regenerate Keys" option (see Importing Items in the Configuration Transfer Tools). No (default = false)

Example

<target name="import">

<importXML ignoremissingobjects="true">

<connection server="${sapphire.db.servername}" port="${sapphire.db.port}" sid="${sapphire.db.sid}" username="${sapphire.db.username}" password="${sapphire.db.password}"/>

<fileset file="${export.dir}\fileA.xml"/>

<fileset file="${export.dir}\fileB.xml"/>

</importXML>

</target>