Get XMLBridge Next Generation at SourceForge.net. Fast, secure and Free Open Source software downloads

A copy of this web site can be found at http://www.brutex.net/XBridgeNG/XBridgeNG.htm

This page was last modified 09:01, 26 January 2008.

XBridgeNG Documentation

XBridgeNG has three aspects:

It defines an XML format that can be used to describe field based records (items), e.g. tickets from a bug tracker. It also defines a way to describe relationships between these items and associations between items and other objects (e.g. file attachments).

It includes several adapters for other software products to enable them to export and import data that is written in the xml format described above. Therefore XBridgeNG acts as a bridge between different tools (currently there are adapters available for QualityCenter, TeamTrack, Perforce, ...). These adapters are written in Java and are wrappers to the proprietary APIs of the tools. XBridgeNG uses Apache Ant as an execution engine. The Apache Ant build file describes the flow of data between the different tools for XBridgeNG. Serial, parallel and n-to-n synchronization of data is possible using regular Apache Ant build file syntax along with the XBridgeNG adapters. While "modern" technologies like web services are a good approach to building software integrations , it is often easier to set up a synchronization based on plain flat xml files (offline use, transport through firewalls, different networks, ...). XBridgeNG is not an integration server.

Getting help: Please use the XBridgeNG Support Forum to submit your help request.

Contents

Architecture

The XBridgeNG package contains an Apache Ant runtime and a suite of so called Ant Tasks.

Idea/ Architecture

System Requirements

XBridgeNG runs on any platform Apache Ant runs on. These are in no particular order:

- Unix such as Solaris and HP-UX, Windows NT-platforms, OS/2 Warp, Novell Netware 6, OpenVMS and MacOS X (please keep in mind that some Ant Tasks may require a more specific platform)

- Sun Java Runtime Version 5 or higher (also known as JRE 1.5)

Windows 9x (Win95, Win98, Win98SE and WinME) has a file system which does not work fully with long file names. Therefore it is recommended to install XBridgeNG and the JDK into directories that have no spaces in the path. Even for WinNT, Win2000, WinXP and Win2k3 this is best practice. MS Vista support has not been verified yet. You may need at least JRE 1.6 (Java 6).

Installation

First verify that your system does meet the System_Requirements. Then [download] the latest binary package from the Sourceforge.net [[1]] project site.

The download consists of one zip file. Unzip it to the desired directory. If you wish to use XBridgeNG as an integration to Serena TeamTrack or Serena Business Mashup Suite 20008 it is recommended to install into

  1. \Program Files\Serena\XBridgeNG

The path may slightly different depending on your systems locale. Change into that directory and open a command shell. You can verify the installation using

  1. bin\ant.bat –diagnostics

You may use any Apache Ant command line parameter as described here Apache Ant Commandline Reference.

Installation tree:

  1. /
  2. ---- XBridgeNG
  3. |
  4. |-- bin/
  5. |-- confdir/
  6. |-- doc/
  7. |-- examples/
  8. |-- lib/
  9. |-- xsl/


The executable batch files are in bin/. They depend on the libraries found in the /lib directory. Apache Ant itself is installed as a set of libraries.

The “example/” directory contains some sample configurations to get started.

The “doc/” directory contains this document and a javadoc.

Any configuration files should go into “confdir/”.

Some basic transformation examples using XSLT are available the “xsl” directory.

Task Reference

Common to all XBridgeNG tasks

Common properties

Parameter Required Default Description
dstdir N Destination directory for export action. Can only be used in conjunction with parameters specifying items by id or by query.
dstfile N Destination file for export action. May not be used together with “dstdir” parameter and requires a parameter that specifies either an item id or an item query.
itemid N Item identifier to reference a single item or multiple items (use comma separated list of ids). Referenced item(s) will get exported to “dstdir” or “dstfile”.
itemquery N Query string that identifies items for export. The syntax is task specific. Found item(s) will get exported to “dstdir” or “dstfile”.
name N <name of task class> A name for the tool addressed by this task. The name will be used for XRef handling.
srcdir N Directory to import from. Any XML file in the specified directory will be imported (ItemDataList format is mandatory).


Common nested elements

The XrefHandler element defines how the system should keep track of the identifiers of the different integrated tools. In short, the XrefHandler knows which ids in tool A belong to which ids in tool B.

Basically this is done by storing these “cross-references” somewhere. The storage method is defined by the choosen XrefHandler implementation. Available implementations are:

Optionally you can start your own handler by implementing the AbstractXrefHandler java class.


xrefhandler

Common properties:

Property Required Default Description
name Y Fully qualified class name of the xrefhandler implementation that should be used.
com.serena.xmlbridge.entities.EmptyXrefHandler

This is the default handler. It simply does nothing. This results in any data import action always creating new items.


com.serena.xmlbridge.entities.XMLFileXrefHandler

The XMLXrefHandler stores the cross references in flat xml files. This is a good starting point for demo or POC purposes. In production environment problems due parallel file accesses may occur.

Parameters are specified using a nested <property> element as follows:

  1. <property name="name" value="value"/>
Property Required Default Description
store N xrefstore.xml Path and name of the XML file to store cross-references in.

Example:

  1. <xrefhandler name="com.serena.xmlbridge.entities.XMLFileXrefHandler">
  2. <property name="store" value="storefile.xml"/>
  3. </xrefhandler>
com.serena.xmlbridge.entities.SQLXrefHandler

The SQLXrefHandler stores the cross references in a relational database using a JDBC database connection.


Parameters are specified using a nested <property> element as follows:

  1. <property name="name" value="value"/>
Property Required Default Value
create N false If set to “true” all required database tables will be created if they do not already exist.
debug N false If set to “true” the handler will print all used sql statements to the console.
jdbcconnect Y JDBC connect string
jdbcdriver Y JDBC driver class
namestore N "XREF_NAMESTORE" Table name for tool name storage
store N "XREF_IDSTORE" Table name for cross-reference storage

Example:

  1. <xrefhandler name="com.serena.xmlbridge.entities.SQLXrefHandler">
  2. <property name="store" value="XREF_STORE"/>
  3. <property name="namestore" value="XREF_NAMESTORE"/>
  4. <property name="jdbcdriver" value="org.apache.derby.jdbc.ClientDriver"/>
  5. <property name="jdbcconnect"
  6. value="jdbc:derby://localhost:1527/xbridgeng;user=admin;password=admin"/>
  7. <property name="create" value="true"/>
  8. </xrefhandler>


exceptionhandler

The ExceptionHandler element is called by the task each time an exception occurs. Depending on the selected ExceptionHandler implementation, handling routines are called. The ExceptionHandler concept is not implemented for all tasks yet.

Available ExceptionHandler:

Optionally you can start your own handler by implementing the AbstractExceptionHandler java class.

Property Required Default Description
name Y Fully qualified class name of the xrefhandler implementation that should be used.


com.serena.xmlbridge.entites.EmptyExceptionHandler

This is the default handler. It simply collects all exception messages and then forwards them into an Apache Ant property. Properties are specified using a nested <property> element as follows:

  1. <property name="name" value="value"/>
Property Required Default Description
dump N false If set to “true” the ItemData causing this exception will be dumped into the exception message. Please note that this also includes any attachment.
errorflagname N “has_error” Name of an Apache Ant variable. The variable will be set to “true” if an exception occurred.
errormessagename N “error_messages” Name of an Apache Ant variable. The variable will contain the exception messages after the task itself has completed.
failonerror N false If set to “true” the exception will be thrown immediately. This will usually break the defined flow. Use for debugging only.
movetodir N ItemData objects causing the exception will be moved to this directory.

Example:

  1. <xrefhandler name="com.serena.xmlbridge.entities.SQLXrefHandler">
  2. <property name="store" value="XREF_STORE"/>
  3. <property name="namestore" value="XREF_NAMESTORE"/>
  4. <property name="jdbcdriver" value="org.apache.derby.jdbc.ClientDriver"/>
  5. <property name="jdbcconnect"
  6. value="jdbc:derby://localhost:1527/xbridgeng;user=admin;password=admin"/>
  7. <property name="create" value="true"/>
  8. </xrefhandler>


com.serena.xmlbridge.entities.ItemExceptionHandler

This handler generates an ItemData object for any exception and optional attaches the original ItemData object that caused the exception to it. Properties are specified using a nested <property> element as follows:

  1. <property name="name" value="value"/>
Property Required Default Description
dstfile Y Were to put the newly created ItemData objects.
errorflagname N “has_error” Name of an Apache Ant variable. The variable will be set to “true” if an exception occurred.
failonerror N false If set to “true” the exception will be thrown immediately. This will usually break the defined flow. Use for debugging only.
name N Tool name that should be used for the <itemName> element wihin the <genericItem>.
project N The ItemData object will contain a “PROJECTID” field within the extended field list, holding the provided value.

The newly generated ItemData object contains a title containing a timestamp and “An exception occurred” and a description containing the exception message. Optional a “PROJECTID” field will be set. The original ItemData causing the error is attached as a file attachment. A result may look like this:

  1. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  2. <ItemDataList xmlns="urn:ttwebservices">
  3. <ItemData>
  4. <genericItem>
  5. <itemID>1184582540218</itemID>
  6. <itemName>Exception Test</itemName>
  7. </genericItem>
  8. <extendedFieldList>
  9. <name>TITLE</name>
  10. <value>Mon Jul 16 12:42:19 CEST 2007 An exception occured.</value>
  11. </extendedFieldList>
  12. <extendedFieldList>
  13. <name>DESCRIPTION</name>
  14. <value>Mon Jul 16 12:42:19 CEST 2007 An error occured. Error message is:
  15. Submit project could not be found.
  16. </value>
  17. </extendedFieldList>
  18. <extendedFieldList>
  19. <name>PROJECTID</name>
  20. <value>Animation Pro</value>
  21. </extendedFieldList>
  22. <extendedFieldList>
  23. <name>ACTIVEINACTIVE</name>
  24. <value>1</value>
  25. </extendedFieldList>
  26. <fileAttachmentList> <name>com.serena.xmlbridge.adapter.ttwebservice.gen.TTItem@bbaa16</name>
  27. <fileName>com.serena.xmlbridge.adapter.ttwebservice.gen.TTItem@bbaa16</fileName>
  28. <showAsImage>false</showAsImage>
  29. <checksum>0</checksum>
  30. <encodedContents>PD94bW[...snipped...]wgdmVycK</encodedContents>
  31. </fileAttachmentList>
  32. </ItemData>
  33. </ItemDataList>

Example:

  1. <exceptionhandler name="com.serena.xmlbridge.entities.ItemExceptionHandler">
  2. <property name="failonerror" value="false"/>
  3. <property name="errorflagname" value="has_error"/>
  4. <property name="project" value="Animation Pro"/>
  5. <property name="dstfile" value="./failed_items.xml"/>
  6. <property name="name" value="Exception Test"/>
  7. </exceptionhandler>


Perforce (P4) Task (P4AdapterTask)

The P4AdapterTask wraps the p4.exe command line tool as an Apache Ant Task. Features include:

This adapter is beta code. The fully qualified class name is “com.serena.xmlbridge.adapter.p4.P4AdapterTask”.


Functionality

The P4AdapterTask can be used to import and export Perforce Jobs from/ into the ItemData xml format. As a backend, Perforce command line (p4) is used to achieve the desired operations. Therefore Perforce command line client must be installed as a prerequisite. The task decides on the given parameters which actions are to be performed. The following actions are available:

Any operation may not include the handling of attachments and/ or notes. Depending on the content of the ItemData file, a new job is added, updated or exported.

Properties

Property Required Default Description
client N Sets the P4CLIENT value.
encoding N “ISO-8859-1” Force output encoding.
executable Y Perforce command line client. May include full qualified path name like “c:/perforce/p4.exe”.
itemquery N "*" Jobview query (-e <value>). Is required for export action. Ex.: “job=job000037”.
limit N 1000 Limits resultset of itemquery size.
password N Sets the P4PASSWD value.
port N Sets the P4PORT value (ex. “localhost:1666”).
systemdrive N "C:" System drive (Windows only).
systemroot N “C:\WINNT” System root (Windows only).
timeout N 100000 Server timeout in milliseconds.
user N Sets P4USER value.


Nested elements


Supported Features Matrix

import export
<extendedFieldList> x x
<fileAttachmentList>
<noteList>
<itemLinkList>
<urlAttachmentList


Serena TeamTrack Task (TTWsAdapterTask)

The TTWsAdapterTask wraps the TTWsAdapter API included in the XBridgeNG package as an Apache Ant Task.

The fully qualified class name is “com.serena.xmlbridge.adapter.ttwebservice.TTWsAdapterTask”.

The task can be registered like this:

  1. <taskdef
  2. name="teamtrack"
  3. classname="com.serena.xmlbridge.adapter.ttwebservice.TTWsAdapterTask"
  4. />

The value for „name“ can be any valid, not already used Apache Ant task name. After registration, the task can be used with the given name.

Functionality

The TTWsAdapterTask can be used to import and export TeamTrack Items from/ into the ItemData xml format. As a backend, TeamTrack web service is used to achieve the desired operations on the TeamTrack side.

The task decides on the given parameters which actions are to be performed. The following actions are available:

Any operation may include the handling of attachments and/ or notes.

Depending on the content of the ItemData file, TeamTrack performs a submit, update or transition with the given item.

Properties

Property Required Default Description
encoding No “UTF-8” Encoding that is used for the resulting xml file (export action).
httpAuthUser No Username that is used for Basic Http Authentication. This is _not_ necessarily a TeamTrack user name. Use this setting if the web service is protected by the web server itself.
httpAuthPass No Password that is used for Basic Http Authentication.
linklevel No 1 Recursive level. This parameter is only used in conjunction with the “relations” parameter and if “relations” is set to “INCLUDE”. In this case, provide an integer how deep the task should resolve relational items. Use with care. Setting this to a high value will have a noticable impact on performance.
relations No “ID-ONLY” Decides how relational fields in TeamTrack should be handled on import and export. (see TTWsAdapterTask#Relations )
serviceLocation Y URL to the TeamTrack web service. Usually this is something like http://server:port/gsoap/gsoap.ssl?ttwebservices.
ttjdbcconnect N (Y) JDBC connection string to the TeamTrack database. This setting is mandatory if “relations=TITLE-ONLY” is used for import action. REMOVED SINCE VERSION 1.1.x!
ttjdbcdriver N (Y) JDBC driver class (fully qualified class name). This setting is mandatory if “relations=”TITLE-ONLY” is used for import action. REMOVED SINCE VERSION 1.1.x!
ttPassword Y Password for the TeamTrack user.
ttUser Y Username for the TeamTrack user.
wsdlLocation Y URL to the TeamTrack web service WSDL file. Ususally this is something like http://server:port/gsoap/ttwebservices.wsdl.


Relations

Possible values for relations:

Only the item id of the relational item will be exported and imported

The display value of the relational item will be used. Please note that the behaviour is slightly different for versions before 1.1.x. Old behavior: This is the value stored within the TS_TITLE database field. This option can not be used if there are relational items that do not have a TS_TITLE attribute. On import, the task tries to find a matching item by doing a database query. In this case the parameters “ttjdbcdriver” and “ttjdbcconnect” must be present.

On export, the complete relational item is included as an inline element. This is always an ItemDataList element. Use the “linklevel” parameter to set the recursion level. This setting can not be used for import.

Nested Elements

Special attributes

You specify which transition should be performed on update, by adding the transition id into a special named field as shown below. Any integer number is valid. Transition Id’s may have a special meaning as follows:

1: use built-in Update transition 2: use built-in Delete transition (physically deletes the item from TeamTrack)

  1. <extendedFieldList>
  2. <name>XBridgeNG:defaultTransition</name>
  3. <value>2</value>
  4. </extendedFieldList>

Supported Features Matrix

import export
<extendedFieldList> x x
<fileAttachmentList> x x
<noteList> x x
<itemLinkList> x x
<urlAttachmentList> x x


Examples

See Examples#TeamTrack.


HP Quality Center Task (QC9AdapterTask)

The QC9Adapter wraps Quality Center Client API (MS COM Module). System requirements:

The fully qualified class name is “com.serena.xmlbridge.adapter.qc9.QC9AdapterTask”.

The task can be registered like this:

  1. <taskdef
  2. name="qc9" classname="com.serena.xmlbridge.adapter.qc9.QC9AdapterTask"
  3. />

The value for „name“ can be any valid, not already used Apache Ant task name. After registration, the task can be used with the given name.

Functionality

The QC9AdapterTask can be used to import and export Quality Center Defects from/ into the ItemData xml format. Support for other QC Objects like Requirements and Test is included but experimental.

The task decides on the given parameters which actions are to be performed. The following actions are available:

Any operation may include the handling of attachments and/ or notes.

Depending on the content of the ItemData file, a submit, update or export with the given item is performed.

Properties

Property Required Default Description
encoding No “UTF-8” Encoding that is used for the resulting xml file (export action).
itemquery No SQL query string. Found items will be exported to dstfile. Example: SELECT * FROM BUG WHERE BG_SUMMARY like “%something%”
qcdomain No “Default” Quality Center domain to connect.
qcpassword No Password for user.
qcproject Yes Quality Center project to connect to.
qcserver Yes Quality Center server url. Example: http://host:port/qcbin
qcuser Yes Quality Center user to connect.
strictmode No false If set to true any invalid field data will throw an exception immediately.
tempdir No system temp dir Temp directory used for file attachment upload. Since version 1.0.2

Nested Elements

Supported Features Matrix

import export
<extendedFieldList> x x
<fileAttachmentList> x x
<noteList> x
<itemLinkList>
<urlAttachmentList> x x

Object Reference

ItemDataList

The ItemDataList is a collection of ItemData objects. Any Ant Task available in XBridgeNG knows how to import and export such an ItemDataList into/ from their connected tool. An ItemDataList may be empty. The following sample snippet represents and ItemDataList containing two ItemData objects.

Sample XML snippet:

  1. <ItemDataList xmlns="urn:ttwebservices">
  2. <ItemData>
  3. <genericItem>
  4. <itemID>1183892816878</itemID>
  5. <itemName>Sample </itemName>
  6. </genericItem>
  7. <extendedFieldList>
  8. <name>TITLE</name>
  9. <value>This is a sample item</value>
  10. </extendedFieldList>
  11. <extendedFieldList>
  12. <name>DESCRIPTION</name>
  13. <value>The details go here</value>
  14. </extendedFieldList>
  15. </ItemData>
  16. <ItemData>
  17. <genericItem>
  18. <itemID>1183892817066</itemID>
  19. <itemName>Sample</itemName>
  20. </genericItem>
  21. <extendedFieldList>
  22. <name>TITLE</name>
  23. <value>Yet another item</value>
  24. </extendedFieldList>
  25. <extendedFieldList>
  26. <name>DESCRIPTION</name>
  27. <value>Details go here</value>
  28. </extendedFieldList>
  29. </ItemData>
  30. </ItemDataList>

ItemData

The ItemData object is the major object. It contains the data that should be handled by the Ant Tasks available in this suite.

Any ItemData object is required to contain exactly one genericItem. Any other included elements are optional and may occur more than once. Data that is organised in attributes (or fields) is transported within the extendedFieldList. Any other elements like noteList, itemLinkList, urlAttachmentList or fileAttachmentList transport data that is not directly contained in the item itself but closely related. It depends on the features of each tool how these additional elements are used and made visible.

Readers with knowledge of the Serena TeamTrack Web Services may have noticed the common elements. Basically the ItemData type is a generalisation of the “TTItem” type which is used by the TeamTrack Web Service. However there are two differences:

These changes were made to have a more independent data format. The available “TTWsAdapter” in the XBridgeNG packages does the conversion between TTItem and ItemData format in both directions. This way the user does not need to deal with the TTItem format specific issues.

Sample XML snippet:

  1. <ItemData>
  2. <genericItem>
  3. <itemID>1004:55</itemID>
  4. <itemName>TeamTrack</itemName>
  5. </genericItem>
  6.  
  7. <extendedFieldList>
  8. <name>CLOSEDATE</name>
  9. <value>2003-03-07T18:25:16+00:00</value>
  10. </extendedFieldList>
  11. <extendedFieldList>
  12. <name>MANAGER</name>
  13. <value>joe</value>
  14. </extendedFieldList>
  15. <extendedFieldList>
  16. <name>EST_TIME_TO_FIX</name>
  17. <value>8:30:00</value>
  18. </extendedFieldList>
  19. <extendedFieldList>
  20. <name>MAILING_LIST</name>
  21. <values>carmen</values>
  22. <values>carol</values>
  23. <values>chad</values>
  24. </extendedFieldList>
  25. <name>DESCRIPTION</name>
  26. <value>The details for this item</value>
  27. </extendedFieldList>
  28. <extendedFieldList>
  29. <name>TITLE</name>
  30. <value>Blabla Test Item</value>
  31. </extendedFieldList>
  32.  
  33. <noteList>
  34. <id>121</id>
  35. <title>This is a test note</title>
  36. <note>Any text that should be included goes here.</note>
  37. <modificationDateTime>2007-04-29T08:31:28+02:00
  38. </modificationDateTime>
  39. </noteList>
  40.  
  41. <urlAttachmentList>
  42. <id>188</id>
  43. <name>http://google.de</name>
  44. <url>http://google.de</url>
  45. </urlAttachmentList>
  46.  
  47. <fileAttachmentList>
  48. <id>199</id>
  49. <name>BUG_3_Cavipe.bat</name>
  50. <fileName>BUG_3_Cavipe.bat</fileName>
  51. <showAsImage>false</showAsImage>
  52. <checksum>0</checksum>
  53. <encodedContents> amF2YSAtamFyICJEOlxFSUdFTkVfREFURUlFTlxORVRCRUFOU1xDYXZpcGVcZGlzdFxDYXZpcGUuamFyIg==</encodedContents>
  54. </fileAttachmentList>
  55.  
  56. </ItemData>


genericItem

The genericItem element contains metadata needed for synchronization handling. These are itemID and itemName. The semantic is that the itemID must be unique within the namespace defined in itemName. The identifier can be any character. In the sense of Teamtrack the genericItem element may look like the following:

  1. <genericItem>
  2. <itemID>1002:123</itemID>
  3. <itemName>TeamTrack System A</itemName>
  4. </genericItem>

If you want to synchronize data between tools that are using the same identifiers you must specify different item names.

fileAttachmentList

The fileAttachmentList element contains a file attachment and metadata describing the attachment (like filename). The attachment itself is included within the xml file. How file attachments are actually handled depends on the receiving/ sending task.

Mandatory elements are:


Example:

  1. <fileAttachmentList>
  2. <id>199</id>
  3. <name>BUG_3_Cavipe.bat</name>
  4. <fileName>BUG_3_Cavipe.bat</fileName>
  5. <showAsImage>false</showAsImage>
  6. <checksum>0</checksum>
  7. <encodedContents> amF2YSAtamFyICJEOlxFSUdFTkVfREFURUlFTlxORVRCRUFOU1xDYXZpcGVcZGlzdFxDYXZpcGUuamFyIg==</encodedContents>
  8. </fileAttachmentList>

Transformations

Naming convention:

  1. <type>_<part>_<name>.xsl
  2.  
  3. <type> = ('filter' | 'function')
  4. <part> = ('ALL' | 'TT' | 'CDO' | 'QC9' | 'P4' | ...)
  5. <name> = your string, no spaces

Examples: function_TT_addItemLink.xsl filter_ALL_removeNotes.xsl


Filter

ALL_removeFileAttachment

Remove all <fileAttachmentList> elements.

Usage:

  1. <xslt in=”${sourcefile}out=”${targetfile}
  2. style=”${basedir}/xsl/filter_ALL_removeFileAttachment.xsl”/>


ALL_removeNoteAttachment

Remove all <noteList> elements.

Usage:

  1. <xslt in=”${sourcefile}out=”${targetfile}
  2. style=”${basedir}/xsl/filter_ALL_removeNoteAttachment.xsl”/>


ALL_removeURLAttachment

Remove all <urlAttachmentList> elements.

  1. <xslt in=”${sourcefile}out=”${targetfile}
  2. style=”${basedir}/xsl/filter_ALL_removeURLAttachment.xsl”/>

Functions

TT_addItemLink

This function adds an <urlAttachment> to each <ItemData> object, based on the <genericItem> and a basis url parameter. The added urlAttachment contains a direct weblink to the TeamTrack item.

Usage:

  1. <xslt in=”${sourcefile}out=”${targetfile}
  2. style=”${basedir}/xsl/function_TT_addItemLink.xsl”>
  3. <param name=”urlbasis” expression=”http://localhost/tmtrack/”/>
  4. </xslt>

Download

Download

Browse Source Code

Javadoc

View Javadoc online