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.
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
\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
bin\ant.bat –diagnostics
You may use any Apache Ant command line parameter as described here Apache Ant Commandline Reference.
Installation tree:
/ ---- XBridgeNG | |-- bin/ |-- confdir/ |-- doc/ |-- examples/ |-- lib/ |-- 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:
- EmptyXrefHandler
- XMLXrefHandler
- SqlXrefHandler
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:
<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:
<xrefhandler name="com.serena.xmlbridge.entities.XMLFileXrefHandler"> <property name="store" value="storefile.xml"/> </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:
<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:
<xrefhandler name="com.serena.xmlbridge.entities.SQLXrefHandler"> <property name="store" value="XREF_STORE"/> <property name="namestore" value="XREF_NAMESTORE"/> <property name="jdbcdriver" value="org.apache.derby.jdbc.ClientDriver"/> <property name="jdbcconnect" value="jdbc:derby://localhost:1527/xbridgeng;user=admin;password=admin"/> <property name="create" value="true"/> </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:
- EmptyExceptionHandler
- ItemExceptionHandler
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:
<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:
<xrefhandler name="com.serena.xmlbridge.entities.SQLXrefHandler"> <property name="store" value="XREF_STORE"/> <property name="namestore" value="XREF_NAMESTORE"/> <property name="jdbcdriver" value="org.apache.derby.jdbc.ClientDriver"/> <property name="jdbcconnect" value="jdbc:derby://localhost:1527/xbridgeng;user=admin;password=admin"/> <property name="create" value="true"/> </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:
<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:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ItemDataList xmlns="urn:ttwebservices"> <ItemData> <genericItem> <itemID>1184582540218</itemID> <itemName>Exception Test</itemName> </genericItem> <extendedFieldList> <name>TITLE</name> <value>Mon Jul 16 12:42:19 CEST 2007 An exception occured.</value> </extendedFieldList> <extendedFieldList> <name>DESCRIPTION</name> <value>Mon Jul 16 12:42:19 CEST 2007 An error occured. Error message is: Submit project could not be found. </value> </extendedFieldList> <extendedFieldList> <name>PROJECTID</name> <value>Animation Pro</value> </extendedFieldList> <extendedFieldList> <name>ACTIVEINACTIVE</name> <value>1</value> </extendedFieldList> <fileAttachmentList> <name>com.serena.xmlbridge.adapter.ttwebservice.gen.TTItem@bbaa16</name> <fileName>com.serena.xmlbridge.adapter.ttwebservice.gen.TTItem@bbaa16</fileName> <showAsImage>false</showAsImage> <checksum>0</checksum> <encodedContents>PD94bW[...snipped...]wgdmVycK</encodedContents> </fileAttachmentList> </ItemData> </ItemDataList>
Example:
<exceptionhandler name="com.serena.xmlbridge.entities.ItemExceptionHandler"> <property name="failonerror" value="false"/> <property name="errorflagname" value="has_error"/> <property name="project" value="Animation Pro"/> <property name="dstfile" value="./failed_items.xml"/> <property name="name" value="Exception Test"/> </exceptionhandler>
Perforce (P4) Task (P4AdapterTask)
The P4AdapterTask wraps the p4.exe command line tool as an Apache Ant Task. Features include:
- Synchronization of P4 jobs with ItemData objects
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:
- import
- export
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:
<taskdef name="teamtrack" classname="com.serena.xmlbridge.adapter.ttwebservice.TTWsAdapterTask" />
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:
- import
- export
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:
- INTERNAL-VALUE (since 1.1.x, formerly: ID-ONLY)
Only the item id of the relational item will be exported and imported
- DISPLAY-VALUE (since 1.1.x, formerly: TITLE-ONLY)
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.
- INCLUDE
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)
<extendedFieldList> <name>XBridgeNG:defaultTransition</name> <value>2</value> </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:
- Microsoft Windows
- Mercury Quality Center 9.x API (Client)
The fully qualified class name is “com.serena.xmlbridge.adapter.qc9.QC9AdapterTask”.
The task can be registered like this:
<taskdef name="qc9" classname="com.serena.xmlbridge.adapter.qc9.QC9AdapterTask" />
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:
- import
- export
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
- < xrefhandler>
- < exeptionhandler>
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:
<ItemDataList xmlns="urn:ttwebservices"> <ItemData> <genericItem> <itemID>1183892816878</itemID> <itemName>Sample </itemName> </genericItem> <extendedFieldList> <name>TITLE</name> <value>This is a sample item</value> </extendedFieldList> <extendedFieldList> <name>DESCRIPTION</name> <value>The details go here</value> </extendedFieldList> </ItemData> <ItemData> <genericItem> <itemID>1183892817066</itemID> <itemName>Sample</itemName> </genericItem> <extendedFieldList> <name>TITLE</name> <value>Yet another item</value> </extendedFieldList> <extendedFieldList> <name>DESCRIPTION</name> <value>Details go here</value> </extendedFieldList> </ItemData> </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:
- The genericItem has the same syntax but a different semantic.
- The fileAttachmentList element used in the ItemData object is more restrictive and requires included elements of the type “FileAttachmentContents” while the TeamTrack Web Service accepts the “FileAttachment” type too.
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:
<ItemData> <genericItem> <itemID>1004:55</itemID> <itemName>TeamTrack</itemName> </genericItem> <extendedFieldList> <name>CLOSEDATE</name> <value>2003-03-07T18:25:16+00:00</value> </extendedFieldList> <extendedFieldList> <name>MANAGER</name> <value>joe</value> </extendedFieldList> <extendedFieldList> <name>EST_TIME_TO_FIX</name> <value>8:30:00</value> </extendedFieldList> <extendedFieldList> <name>MAILING_LIST</name> <values>carmen</values> <values>carol</values> <values>chad</values> </extendedFieldList> <name>DESCRIPTION</name> <value>The details for this item</value> </extendedFieldList> <extendedFieldList> <name>TITLE</name> <value>Blabla Test Item</value> </extendedFieldList> <noteList> <id>121</id> <title>This is a test note</title> <note>Any text that should be included goes here.</note> <modificationDateTime>2007-04-29T08:31:28+02:00 </modificationDateTime> </noteList> <urlAttachmentList> <id>188</id> <name>http://google.de</name> <url>http://google.de</url> </urlAttachmentList> <fileAttachmentList> <id>199</id> <name>BUG_3_Cavipe.bat</name> <fileName>BUG_3_Cavipe.bat</fileName> <showAsImage>false</showAsImage> <checksum>0</checksum> <encodedContents> amF2YSAtamFyICJEOlxFSUdFTkVfREFURUlFTlxORVRCRUFOU1xDYXZpcGVcZGlzdFxDYXZpcGUuamFyIg==</encodedContents> </fileAttachmentList> </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:
<genericItem> <itemID>1002:123</itemID> <itemName>TeamTrack System A</itemName> </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:
- <fileName>
- <encodedContents>
Example:
<fileAttachmentList> <id>199</id> <name>BUG_3_Cavipe.bat</name> <fileName>BUG_3_Cavipe.bat</fileName> <showAsImage>false</showAsImage> <checksum>0</checksum> <encodedContents> amF2YSAtamFyICJEOlxFSUdFTkVfREFURUlFTlxORVRCRUFOU1xDYXZpcGVcZGlzdFxDYXZpcGUuamFyIg==</encodedContents> </fileAttachmentList>
Transformations
Naming convention:
<type>_<part>_<name>.xsl <type> = ('filter' | 'function') <part> = ('ALL' | 'TT' | 'CDO' | 'QC9' | 'P4' | ...) <name> = your string, no spaces
Examples: function_TT_addItemLink.xsl filter_ALL_removeNotes.xsl
Filter
ALL_removeFileAttachment
Remove all <fileAttachmentList> elements.
Usage:
<xslt in=”${sourcefile}” out=”${targetfile}” style=”${basedir}/xsl/filter_ALL_removeFileAttachment.xsl”/>
ALL_removeNoteAttachment
Remove all <noteList> elements.
Usage:
<xslt in=”${sourcefile}” out=”${targetfile}” style=”${basedir}/xsl/filter_ALL_removeNoteAttachment.xsl”/>
ALL_removeURLAttachment
Remove all <urlAttachmentList> elements.
<xslt in=”${sourcefile}” out=”${targetfile}” 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:
<xslt in=”${sourcefile}” out=”${targetfile}” style=”${basedir}/xsl/function_TT_addItemLink.xsl”> <param name=”urlbasis” expression=”http://localhost/tmtrack/”/> </xslt>