text:
-:�@oa�, mimetypeapplication/epub+zipPK -:�@ iTunesMetadata.plists��
For Release 220.127.116.11.0, the Oracle Fusion Middleware User Guide for Oracle Team Productivity Center replaces the non-context sensitive online help that was available in previous releases of Oracle Team Productivity Center. It incorporates the information on working with Oracle Team Productivity Center, administering Oracle Team Productivity Center, and working with Oracle Team Productivity Center connectors.
For additional information on Oracle Team Productivity Center in this release, see the Oracle Team Productivity Center page on the Oracle Technology Network at
For changes made to Oracle JDeveloper and Oracle Application Development Framework (Oracle ADF) for this release, see the What's New page on the Oracle Technology Network at
This chapter describes how to develop connectors between Oracle Team Productivity Center and external data repositories, such as bug databases, feature tracking systems, and any other repository of data used by a team for development. It also describes how to work with Oracle Team Productivity Center connectors after you have created them. This includes error handling, adding help, packaging the connectors for distribution, and internationalization.
Oracle Team Productivity Center connectors provide a framework to integrate third-party repositories with JDeveloper. Standard work item interfaces allow third-party connectors to fetch data from their backend repositories and present them in a standard format. The declarative user interface approach gives connector writers the freedom to lay out UI controls in many flexible ways, without writing an extensive amount of code. JDeveloper then combines the data and UI elements at runtime, and presents repository objects in a coherent way that JDeveloper users already are familiar with.
This chapter includes the following sections:
Section 4.1, "About Working with Oracle Team Productivity Center Connectors"
Section 4.2, "Creating Oracle Team Productivity Center Connectors"
Section 4.3, "Handling Oracle Team Productivity Center Connector Errors"
Section 4.4, "Adding Help to an Oracle Team Productivity Center Connector"
Section 4.6, "Team Productivity Center Connector Internationalization"
Developing your own connectors for Team Productivity Center begins with an understanding of connector architecture. The architecture of an Oracle Team Productivity Center connector is organized to provide three primary functions:
Data fetching from the work item repository served by the connector.
Runtime UI component tree generation inside the Team Productivity Center client.
Display of UI controls and data in work item editor that ties the repository data to UI components.
Each work item connector implements the
WorkitemConnector interface, and optionally
WorkitemAttachment interface if the repository this connector uses supports attachments. The
WorkitemConnector interface specifies methods for end user logging into and out of the repository, basic Create, Read, Update and Delete (CRUD) operations on work items, and retrieving query results. Based on the capabilities of the backend repository, Connector writer determines what
WorkitemConnector methods to implement to expose the backend repository functionalities. When implementing these selected methods, connector writers use the appropriate APIs (or Web services) available from the backend repository. After data is collected through the APIs, it needs to be converted to the work item data structure that the connector writer defines.
After the connector obtains the work item data from the repository, Oracle Team Productivity Center's declarative UI framework reads the work item UI definition defined by the connector writer and binds the data with their corresponding UI controls. The Oracle Productivity Center provides a metadata-driven UI framework in which connector writers can develop a work item UI layout XML file by using the pre-defined UI tags. Preferably, the connector writer authors the UI layout that conforms to JDeveloper look and feel, while maintaining the behaviors of its native application as much as possible. This way the end users will have the same experience when navigating the UI in JDeveloper as well as in its native application.
When both work item data and its UI components tree are available, the
WorkitemEditor, a special editor inside JDeveloper, binds the data to the UI controls and displays them inside the editor.
Oracle Team Productivity Center supports a dynamic work item model and UI at runtime. For certain repositories, the work item model and/or UI are determined by some work item instance field value(s) or a pre-defined condition. Oracle Team Productivity Center provides the flexibility to show a different UI layout at runtime by exposing methods in the
WorkitemConnector interface.
The Oracle Team Productivity Center is provided by default with the Task Repository connector. All other connectors require that you download them from the JDeveloper Update Center, using the Check for Updates wizard.
To download a connector extension:
Select Help > Check for Updates.
In the Check for Updates wizard, select Search Update Centers.
Make sure that the Open Source and Partner Extensions center is selected, and click Next.
On the Updates page, scroll through the list and select the Oracle Team Productivity Center connectors that you wish to download, and then click Next.
Click Finish.
Online help for each of these connectors will be available after you download and install them. You can also refer to the contents and structure of these connectors as samples while developing your own connector.
For more information, see the "How to Install Extensions with Check for Updates" section in the Oracle Fusion Middleware User Guide for Oracle JDeveloper.
To understand the way the preceding information fits together in practice, consider the following example using the JIRA repository:
You double-click on a work item that represents a query titled "My P1 Issues." JDeveloper opens the query, displays the query criteria and executes the query to show the results in a list. You can then double-click on a particular issue in the result list; JDeveloper opens a new work item editor and shows the selected issue's details. Here is the call sequence represented by this example:
UI framework gets the query information from the TPC database for "My P1 Issues."
UI framework finds the JIRA connector instance and calls the method
getQueryResults on the JIRA connector and sends in the query criteria.
JIRA connector returns a list of Work Item objects that match the JIRA work item object definition.
TPC framework shows the list of work items in the results list of the query.
When the user double clicks on particular work item, UI framework calls the
getWorkitem() method on the JIRA connector and passes the issue ID.
Inside the JIRA connector instance,
getWorkitem() uses the JIRA SOAP interface to retrieve the issue data.
When the SOAP interface returns the data,
getWorkitem() converts it to a JIRA Workitem object.
UI framework creates a work item editor.
The work item editor now loads the issue UI page by calling
getUIRegionName() and then generating the UI component tree.
The work item editor then binds the data to their UI controls.
The work item editor, through different renderers, displays the issue data and their associated UI controls.
In this example, you define the XML data objects to hold the various types of objects inside your repository. The name of this file must be specified in the
connector.xml file as the
modelFileName. You create this model file and put it in under your project in the
src/META-INF folder.
You can use tags in
workitem-object.xsd to describe work item data in this definition file. This file specifies the fields to expose in the Team Productivity Center, default columns to show in a query result list, and list of value definitions and the data source to use for getting their data.
workitem-object.xsd is located in the file
almcommon-api.jar. This file, along with the Oracle Team Productivity CenterConnector Tag Guide
tpctagdoc.zip, is distributed under the directory
Example 4-1 is an example work item definition file (
Example 4-1 Sample Work Definition File
<?xml version="1.0" encoding="windows-1252"?> <RepositoryModel resName="res" resFile="/META-INF/res/modelresource.xml"> <WorkItem data-source="rpthead" id-def="TASKID" id-label="${res.TASK_ID}" label-def="TASKID" name="${res.TASK_NAME}" type="Task" subject-def="DESC" webURLHandler="oracle.sampleconnector.model.TaskWebReferenceImpl" supportSearchByID = "true" xmlns="http://www.oracle.com/alm" version="184.108.40.206"> <Fields> <Field name="TASKID" label="${res.TASK_ID}" type="number" readOnly="true"/> <Field name="DESC" label="${res.TASK_DESC}" required="true" maxLength="80" type="string"/> <Field name="OWNER" label="${res.TASK_OWNER}" defaultValue="" controlType="lov" type="string" lovDef="owner_lov"/> <Field name="STATUS" label="${res.TASK_STATUS}" type="number" required="true" controlType="choice" lovDef="statusLookUp"/> <Field name="DUEDATE" label="${res.TASK_DUEDATE}" type="date" readOnly="true"/> <Field name="URL" label="${res.TASK_URL}" maxLength="255" type="string"/> </Fields> <QueryListColumns> <FieldRef name="TASKID"/> <FieldRef name="DESC"/> <FieldRef name="OWNER"/> <FieldRef name="STATUS"/> </QueryListColumns> <WebResource> <URLDef name="URL" archorOn="label"/> <URLDef name="TASKID" archorOn="field"/> </WebResource> <LovDefs> <LovDef name="owner_lov" list-source="users"> <CriteriaMap> <Map listFieldRef="USERID" fieldRef="OWNER"/> </CriteriaMap> <FieldMap> <Map listFieldRef="USERNAME" fieldRef="OWNER"/> </FieldMap> <DisplayList> <FieldRef name="USERID"/> <FieldRef name="USERNAME"/> </DisplayList> </LovDef> <LovDef name="statusLookUp" list-source="status"> <FieldMap> <Map listFieldRef="SID" fieldRef="STATUS"/> </FieldMap> <DisplayList> <FieldRef name="SID"/> <FieldRef name="SDESC"/> </DisplayList> </LovDef> </LovDefs> <DataSources> <DataSource name="users" id-def="USERID"> <Field name="USERID" label="${res.USER_ID}" type="string"/> <Field name="USERNAME" label="${res.USER_NAME}" type="string"/> </DataSource> <DataSource name="priority" id-def="PID"> <Field name="PID" type="number"/> <Field name="PDESC" type="string"/> </DataSource> <DataSource name="status" id-def="SID"> <Field name="SID" type="number"/> <Field name="SDESC" type="string"/> </DataSource> </DataSources> </WorkItem> </RepositoryModel>
Table 4-1 lists the tags used and their descriptions.
Table 4-1 Repository Data Configuration Tags
|Configuration Tag
Encloses all types of work items used for this connector.
Name of the resource bundle. It is used as a name space to identify runtime labels based on the symbols specified.For example,
Path of the resource bundle file for the connector.
Refers to backend repository source. It could be a database table.
Field use to uniquely identify a work item. In most cases, it is the work item's
Field used as a Subject field during tagging a work item or creating relationship between work items.
The work item's type or category. Since you can specify multiple work items with different type in the connector model definition file, the work item's type is used to construct a URL editor for the work item at runtime. The type is also showed in certain UI elements, like right mouse menu items in various work item's pages.
XML name space.
Version of the model definition file.
Encloses all fields used for the repository object
Name of the field.
Display label used for the field in various work item's pages, such as detail UI and query UI.
Data type of the field. Valid values are "
If set to true, an asterisk (*) will show up before the field label to indicate the field is a required field. Default = false.
For information on which UI controls to use., see Section 4.2.5, "How to Present Data Declaratively with the Team Productivity Center UI."
Name of an LOV definition to use if the
If set to true, the corresponding control is grayed out and the field value is in read only mode. Default = false.
If set to
This sets the maximum characters that can be entered into the field.
Encloses all List of Value (LOV) definitions used for the repository fields.
Definition of an LOV.
Name of the LOV.
Name of a data source to use for retrieving its data. See DataSource.
Encloses all data sources used by LOVs.
Definition of a data source.
Name of a data source.
Object type or table name in the backend repository.
List of default columns to show in the query result list.
Section that describes the fields that are hyperlinked.
A child of
The name of the field from the field list.
Whether the underlined hyperlink should be on the label or the actual value. Valid values are "
workitem.properties file is what Team Productivity Center uses to store the listeners (java class to invoke when any event happens regarding work item). Edit this file to include specific listeners that your connector relies on for user input.
When building your connector extension, make sure the
workitem.properties file is included in your connector bundle.
The Team Productivity Center connector begins as a JDeveloper extension project. It uses a configuration file (in XML) to store and manage parameters for creating the connector instance. The connector also defines the data used by the repository so that JDeveloper can interpret it, retrieves data from the repository, and uses the Team Productivity Center UI for presenting data within JDeveloper. The remaining sections provide more details on each task and show sample code for implementing the
WorkItemConnector interface.
Team Productivity Center connectors are created as JDeveloper extensions. This allows them to integrate with JDeveloper and also provides a framework for packaging and distributing the connector through the JDeveloper Check for Updates feature, once the connector development is completed. This provides a well-known mechanism for distributing connectors to your development team.
The following steps provide an overview of the process of creating an Oracle Team Productivity Center connector. Details of many of the procedures listed here are available in the Oracle® Fusion Middleware User Guide for Oracle JDeveloper.
To create an Oracle Team Productivity Center connector:
Create an JDeveloper Extension Project to build the connector.: select File > New > All Featu ��res > Client Tier > Extension Development.
Write the connector configuration XML file. You need to provide connector configuration parameters to be used by the Team Productivity Center installer. The parameters will be treated as seed data and entered into the Team Productivity Center database. They will be used at runtime when creating an instance of the connector.
For more information, see Section 4.2.2, "How to Create an Oracle Team Productivity Center Connector Configuration File."
Determine what object types will be exposed to Oracle Team Productivity Center. For example, the writer of an MS Project Server connector may decide to show task, project, and resource data, so there will be three object types.
Write the repository object definition XML file. This file provides field details on each object type, default label, default UI control type to use, whether it is required, etc.
For more information, see Section 4.1.7, "How to Define Team Productivity Center Repository Data."
If you are using specific listeners, add them to the workitem.properties file and make sure that file is included in the connector bundle.
For more information, see Section 4.1.8, "How to Add Listeners to the Connector."
Write the connector UI layout XML file. This lets you lay out the UI by using UI tags provided by the Team Productivity Center declarative UI framework.
Create a class that implements
WorkItemConnector and (optionally)
WorkItemAttachment interface methods. This class will use the appropriate APIs available from the backend repository to establish a connection, send and receive repository data, and convert the data to work item format that Team Productivity Center uses.
Provide context-sensitive help files. The help file is loaded by the JDeveloper Help Center when the user presses F1 with the work item detail UI in focus.
For more information, see Section 4.4.1, "How to Add Help to the Team Productivity Center Connector."
Provide resource bundle files for multi-language support.
For more information, see Section 4.5.4, "How to Generate the Connector Bundle File."
Package the connector into the appropriate ZIP format for deployment.
The remaining sections provide more details on each task and show sample code for implementing the
WorkItemConnector interface.
The connector configuration XML file contains the parameters used when creating a runtime connector instance. The parameters can be set at the team level or at the server level. Oracle Team Productivity Center Installer reads in this configuration file during installation and populates seed data to Team Productivity Center database tables.
The connector.xml file will need to be created so that you can add parameters for connector that the team leader or administrator can define values for.
To create the connector.xml file:
Right-click on your extension project in the Application Navigator.
Select New > XML > XML Document.
Name this file connector.xml and save it under your project in the src/META-INF folder.
This configuration file uses tags defined the connector.xsd file, which is located in the
almcommon-api.jar file. You can find this JAR file under your JDeveloper install folder:
Example 4-2 contains an example of a configuration file:
Example 4-2 Configuration file sample code
<?xml version="1.0" encoding="UTF-8"?> <ConnectorDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/alm connector.xsd" xmlns="http://www.oracle.com/alm"> <configuration id="Sample" className="oracle.sampleconnector.model.SampleConnectorService" repositoryType="Work Item" uiFileName="/META-INF/SampleUI.xml" modelFileName="/META-INF/SampleDef.xml" version="1.0"> <parameter> <name>SampleParam1</name> <defaultValue>Default value 1</defaultValue> <label> <locale>US</locale> <value>Sample Param 1</value> </label> <description>This is the sample admin param one</description> <accessLevel>ALM-Admin</accessLevel> </parameter> <parameter> <name>SampleParam2</name> <defaultValue>Default value 2</defaultValue> <label> <locale>US</locale> <value>Sample Param 2</value> </label> <description>This is the sample admin param two</description> <accessLevel>ALM-Admin</accessLevel> </parameter> <parameter> <name>SampleTeamParam</name> <defaultValue>Sample Team Param</defaultValue> <label> <locale>US</locale> <value>Sample Team Param</value> </label> <description>This is a sample team parameter</description> <accessLevel>Team-Admin</accessLevel> </parameter> </configuration> </ConnectorDefinition>
Table 4-2 lists the tags used and their descriptions.
Table 4-2 Tags used in connector.xml
|Configuration Tag
Name of the connector
Connector class to load when creating a connector instance during runtime.
Path to a file inside the connector jar file that contains the connector UI definitions
Path to a file inside the connector jar file that contains the connector model definitions
Current connector version. Any new/upgrade connector package should use a new version.
Specifies each of configurable parameters
Parameter name
Display text to use in the Team Administration UI (or Admin UI)
Localization support
Value for the specified locale
A brief description of what this parameter does. It will be displayed in the Admin UI
ALM-Admin - indicates that this parameter can be configured only by a TPC Administrator in the Admin UI > Repositories tab
Team-Admin - indicates that this parameter can be configured by a Team Administrator in the Admin UI > Teams > Repositories tab
Developers of connectors for Team Productivity Center can provide connector-specific functionalities by customizing the work item UI control behavior.
Team Productivity Center provides a connector level configuration file,
tpc-config.xml, for registering all metadata resources. This file should be put under
src/META-INF/ in the connector source code directory.
For details on the tags and attributes supported in the configuration file, see the Oracle Fusion Middleware Tag Reference for Oracle Team Productivity Center Connectors.
To write a custom managed bean:
When you write a connector for Team Productivity Center, you can write a customized managed bean for any value binding support, as shown in the following steps.
Register a managed bean entry in the file
tpc-config.xml, as shown in Example 4-3:
Implement the
LabelBean, as shown inExample 4-4:
Use the managed bean in either the work item definition metadata file (for a work item field, for example), or a label attribute for a UI control in the UI metadata file:
To write a customized UI listener:
You can also write a customized UI listener and register it for a control in the work item UI metadata by performing the following steps:
Register the listener in
tpc-config.xml as shown in Example 4-5:
OpenTaskListener class:
Example 4-6 Implementing Class OpenTaskListener
package oracle.alm.sample.view; import java.awt.event.ActionEvent; import java.awt.event.ActionListener; import java.util.List; import oracle.alm.connector.data.WorkItem; import oracle.alm.view.application.ViewManager; import oracle.alm.view.context.AlmELContext; import oracle.alm.view.model.AlmDataTableModel; import oracle.alm.view.uicomponents.AlmComponent; import oracle.alm.view.uicomponents.AlmContextMenuComponent; import oracle.alm.view.uicomponents.AlmTableComponent; import oracle.alm.view.uicomponents.RenderingContext; public class OpenTaskListener implements ActionListener, AlmScope { public OpenTaskListener(RenderingContext rcontext, AlmComponent component) { super(); _rcontext = rcontext; _component = component; } public void actionPerformed(ActionEvent e) { if (_component instanceof AlmContextMenuComponent) { AlmComponent parent = _component.getParent(); if (parent instanceof AlmTableComponent) { AlmTableComponent tableComp = (AlmTableComponent) parent; List<Integer> rows = tableComp.getSelectedRows(); if (rows != null) { ViewManager vmanger = ViewManager.getInstance(); for (int row: rows) { AlmELContext elcontext = vmanger.getELContext(_rcontext); AlmDataTableModel dataModel = tableComp.getValue(elcontext); Object selectedValue = dataModel.getSelectedItem(row); if (selectedValue instanceof WorkItem) { String wiType = _rcontext.getCurrentWorkItemType(); String reposName = _rcontext.getCurrentReposName(); String reposId = _rcontext.getCurrentReposId(); vmanger.OpenWorkItemInEditor(((WorkItem) selectedValue), wiType, reposName, reposId); } } } } } } public void setRenderingContext(RenderingContext rc){_rcontext = rc}; public RenderingContext getRenderingContext(){return _rcontext}; public void setSourceComponent(AlmComponent component) {_component = component}; public AlmComponent getSourceComponent() {return _component}; private RenderingContext _rcontext; private AlmComponent _component;}
Use the customized listener in the work item UI metadata:
Example 4-7 Using customized listener in a work item
<?xml version="1.0" encoding="windows-1252" ?> <regions resFile="/META-INF/res/uiresources.xml"> <region id="Default" helpTopicId="f1_connector_sample_htm"> <formLayout columns="1" blockSize="10" fieldWidth="400"> <inputText label="#{workitemmodel.labels.TASKID}" value="#{workitemmodel.values.TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.DESC}" value="#{workitemmodel.values.DESC}"/> <listOfValues label="#{workitemmodel.labels.OWNER}" value="#{workitemmodel.values.OWNER}" source="OWNER" pprTargets="statusID"/> <comboBox label="#{workitemmodel.labels.STATUS}" value="#{workitemmodel.values.STATUS}" valueSet="#{workitemmodel.listItems.STATUS}" readOnly="true" id="statusID"/> <inputDate label="#{workitemmodel.labels.DUEDATE}" value="#{workitemmodel.values.DUEDATE}"/> <inputText label="#{workitemmodel.labels.URL}" value="#{workitemmodel.values.URL}"/> </formLayout> <panelLayout> <action text="Open Task" actionListener="${opentask}"/> </panelLayout> </region> </regions>
To customize context menu action:
You can add customized menu items when the user clicks the right mouse button on the query result table. Perform the following steps:
Register the listener in
tpc-config.xml and specify the menu item details:
SaveTaskListener class:
Example 4-9 Implementing class SaveTaskListener
package oracle.alm.sample.model; import java.awt.event.ActionEvent; import java.awt.event.ActionListener; import java.util.List; import javax.swing.JOptionPane; import oracle.alm.connector.data.WorkItem; import oracle.alm.view.application.ViewManager; import oracle.alm.view.context.AlmELContext; import oracle.alm.view.model.AlmDataTableModel; import oracle.alm.view.uicomponents.AlmComponent; import oracle.alm.view.uicomponents.AlmContextMenuComponent; import oracle.alm.view.uicomponents.AlmTableComponent; import oracle.alm.view.uicomponents.RenderingContext; public class SaveTaskListener implements ActionListener, AlmScope { public SaveTaskListener(RenderingContext rcontext, AlmComponent component) { super(); if (component instanceof AlmContextMenuComponent) _almComponent = (AlmContextMenuComponent) component; _renderingContext = rcontext; } public void actionPerformed(ActionEvent e) { ViewManager vmgr = ViewManager.getInstance(); //First get the corresponding AlmTableComponent AlmComponent parent = _almComponent.getParent(); if (parent instanceof AlmTableComponent) { AlmTableComponent tableComp = (AlmTableComponent) parent; //Then call public API on tableComp to get selected rows List&l;Integer> rows = tableComp.getSelectedRows(); if (rows != null) { int row = rows.size(); String cs = ""; if (row == 1) { //show the ID and subject of the selected item //Then get the selected value object throw the tableComp's UI model. ViewManager vmanger = ViewManager.getInstance(); AlmELContext elcontext = vmanger.getELContext(_renderingContext); AlmDataTableModel dataModel = tableComp.getValue(elcontext); Object selectedValue = dataModel.getSelectedItem(row); if (selectedValue instanceof WorkItem) { cs = "Save Task listener: work item "; WorkItem wi = (WorkItem)selectedValue; cs += wi.getRowKey() + " with subject \'"; cs += wi.getSubject() + "\' has been selected."; } } else if (row > 1) { //show the number of rows selected cs = "Save Task listener: " + Integer.toString(row) + " rows selected"; } JOptionPane.showMessageDialog(vmgr.getIDEMain(), cs); } } } public void setRenderingContext(RenderingContext rc){_ renderingContext = rc}; public RenderingContext getRenderingContext(){return _ renderingContext }; public void setSourceComponent(AlmComponent component) {_almComponent = component}; public AlmComponent getSourceComponent() {return _almComponent }; AlmContextMenuComponent _almComponent; RenderingContext _renderingContext; }
If the connector needs to use the HTTP protocol to fetch data through a firewall that JDeveloper is running behind, the following special modifications are required.
In JDeveloper, select Tools > Preferences.
In the Preferences dialog, open the Web Browser and Proxy node.
Check the Use Proxy check box and enter the values for Host Name, Port, and Exceptions.
The connector writer needs to set the proxy configuration for its
HttpClient inside the connector code where it needs to fetch data (for example, inside the
getQueryResult() API).
Example 4-10 Set Proxy Configuration Inside Connector Code
HttpClient httpclient = new HttpClient(); String proxyHost = System.getProperty("http.proxyHost"); String proxyPort = System.getProperty("http.proxyPort"); Boolean useProxy = null; if (proxyHost != null && !proxyHost.isEmpty()&& proxyPort != null && !proxyPort.isEmpty()) { String proxyExceptions = System.getProperty("http.nonProxyHosts"); useProxy = (proxyExceptions == null); if (!useProxy) { String host = ""; try { URL url = new URL(getServerURL()); host = url.getHost(); useProxy = true; } catch (Exception e) { e.printStackTrace(); } proxyExceptions = proxyExceptions.replace("*", ".*"); useProxy = (Pattern.matches(proxyExceptions, host) == false); } } if (useProxy != null && useProxy.equals(Boolean.TRUE)) httpclient.getHostConfiguration().setProxy(proxyHost, Integer.parseInt(proxyPort));
Oracle Team Productivity Center has a framework that supports declarative UI for any connector. Connector writers can use the UI tags defined in
workitem-ui.xsd to lay out the work item UI. Basic UI elements like input text, radio buttons, combo box, checkbox, pick list or List-Of-Values (LOV), are all supported.
This step defines the XML data objects to hold the UI definition in order to show your repository objects to the user. The name of this file must be specified in the connector.xml file as the
uiFileName. You can create this UI file and put it in under your project in the
src/META-INF folder.
workitem-ui.xsd is located in the file
By using the pre-defined
controlType defaults in the model definition, the UI can be laid out easily by simply using a
formLayout component that automatically picks up the control tags from the model. This section shows several examples of how this can be done.
Example 4-11 Simple Method for Displaying Work Item UI Page
<?xml version="1.0" encoding="windows-1252" ?> <regions resFile="/META-INF/res/uiresources.xml"> <region name="Easy" helpTopicId="f1_connector_sample_htm"> <formLayout value="${workitemmodel}" columns="1" blockSize="10"/> </region> </regions>
Table 4-3 UI tags used in preceding example
|UI Tag
Encapsulation of all UI regions used
Specifies the resource bundle file to use for multi language support
One page layout identified by its name attribute
Tells JDeveloper which help file name to use (from within the connector jar file)
It has value of "
This sets the number of columns to lay out the form into.
This means after every blockSize rows a line separator will be added
Tells which row(s) from the model will span to the entire row of the page. If it is "1, 3, 5" then the 1st, 3rd, and 5th rows will span the entire row of the page.
To show a UI page using an explicit layout:
This example shows the same UI as in Example 4-11, but uses an explicit layout instead. This is necessary if you have multiple UI views of the same data model. For example, you would like only a subset of the fields to be visible when creating a new instance of an object but as soon as it is saved, all the fields become visible.
Example 4-12 Explicit Layout for UI page
<?xml version="1.0" encoding="windows-1252" ?> <regions resFile="/META-INF/res/uiresources.xml"> <region name="Default" helpTopicId="f1_connector_sample_htm"> <formLayout columns="1" blockSize="10" > <inputText label="#{workitemmodel.labels.TASKID}" value="#{workitemmodel.values.TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.DESC}" value="#{workitemmodel.values.DESC}"/> <listOfValues label="#{workitemmodel.labels.OWNER}" value="#{workitemmodel.values.OWNER}" srcAttr="OWNER" lovDef="#{workitemmodel.lovDefs.OWNER}"/> <comboxBox label="#{workitemmodel.labels.STATUS}" value="#{workitemmodel.values.STATUS}" valueSet="#{workitemmodel.listItems.STATUS}"/> <inputDate label="#{workitemmodel.labels.DUEDATE}" value="#{workitemmodel.values.DUEDATE}"/> <inputText label="#{workitemmodel.labels.URL}" value="#{workitemmodel.values.URL}"/> </formLayout> </region> </regions>
To lay out more complicated UI using panels:
You can also lay out controls using panels for more complicated UI layouts. Panels have the property of being horizontal or vertical. Panels can also be nested.
Example 4-13 Control layout using panels
<?xml version="1.0" encoding="windows-1252" ?> <regions resFile="/META-INF/res/uiresources.xml"> <region name="Default" helpTopicId="f1_connector_sample_htm"> <panelLayout layout="horizontal"> <formLayout columns="1" blockSize="10" > <inputText label="#{workitemmodel.labels.TASKID}" value="#{workitemmodel.values.TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.DESC}" value="#{workitemmodel.values.DESC}"/> <listOfValues label="#{workitemmodel.labels.OWNER}" value="#{workitemmodel.values.OWNER}" srcAttr="OWNER" lovDef="#{workitemmodel.lovDefs.OWNER}"/> <comboxBox label="#{workitemmodel.labels.STATUS}" value="#{workitemmodel.values.STATUS}" valueSet="#{workitemmodel.listItems.STATUS}"/> <inputDate label="#{workitemmodel.labels.DUEDATE}" value="#{workitemmodel.values.DUEDATE}"/> <inputText label="#{workitemmodel.labels.URL}" value="#{workitemmodel.values.URL}"/> </formLayout> <textEditor value="#{workitemmodel.values.BIGDESC}"/> </region> </regions>
After the model and UI layouts for different work item types are defined, the next step is to implement the methods on the
WorkItemConnector interface, and the methods on
WorkItemAttachment interface (if the connector supports attachments). This topic provides details on these methods.
Before you can implement these methods, you need to add the location of the Team Productivity Center JAR files to your project so you can pick up the appropriate classes for the
WorkItemConnector and
WorkItemAttachment interfaces.
To add the location of Team Productivity Center JAR files to your project:
Double-click on your extension project, and then select Project Properties > Libraries and Classpath.
On the right side, select Add JAR/Directory.
Navigate to where you installed JDeveloper. Under the
JDev/Extensions/oracle.teamproductivitycenter/lib folder, locate the file
almcommon-ip.jar and include that.
Now that the JAR is added, you can implement the interfaces for the
To implement the interface:
Select File > New.
Select General > Java > Java Class.
In the Create Java Class wizard, enter your class and package name.
In the Optional Attributes section, click the plus to implement an interface.
In the Class and Package Browser, select the Hierarchy tab and then find the following class:
oracle/alm/connector/WorkItemConnector. If you intend to implement the
WorkItemAttachment interface, select that also using the
CTRL key.
Click OK.
This will provide you with a skeleton file that has all the methods that you must implement.
Table 4-6 Method Summary
init(Map sessionContext)
Initializes the connector instance on the client side, and builds the connector's physical connection parameters for its corresponding repository
login(Map sessionContext, String userID, String password)
Establishes a user connection between the connector instance on the client side and the backend repository
logout(Map sessionContext)
Disconnect the user from the backend repository. State can be saved using the data hash structure.
setWorkItemDefs(Map sesion, Map<String, WorkItemDef> wiDefs)
Framework constructs the runtime data structures for the work item types defined in the connector model definition
getQueryResult(Map sessionContext, String wiType, QueryInfo query)
Retrieves the query result set that satisfies the query criteria defined by QueryInfo
getWorkItem(Map sessionContext, String wiType, WorkItem workItem)
Retrieves a specific work item by its type and unique identifier
updateWorkItem(Map sessionContext, String wiType, WorkItem workItem)
Updates an existing work item by its type and unique identifier
createWorkItem(Map sessionContext, String wiType, WorkItem workItem)
Creates a new work item on its backend repository for the specified type
deleteWorkItem(Map sessionContext, String wiType, WorkItem workItem)
Deletes a work item from its backend repository
getLOVQueryResult(Map sessionContext, QueryInfo query, String fieldName)
Retrieves the value set for a predefined LOV (List of Value)
IsAttachmentSupported (Map sessionContext, WorkItem wi)
Determines if attachment is supported for the specified work item. If yes, the work item model needs to implement the
getUIRegionName(Map sessionContext, String wiType, WorkItem wi)
Retrieves the region name defined in the connector UI XML
hasDynamicUI(Map session)
If the connector supports dynamic UI, returns true
getDynamicUI(Map session, String currentUI)
Retrieves the new work item UI definition XML string
hasDynamicModel(Map session)
If the connector supports dynamic model, returns true
getDynamicModel (Map session, String currentModel)
Retrieves the new work item model definition XML string
In certain scenarios, the work item detail page needs to be refreshed to a new layout based on some custom action in the existing layout. For example, users may make a new value selection from a combo box, or a date change from a date time picker, or just simply clicking a button in the page.
When a task is shown in its detail editor, there is a "Status" combination box in its base UI:
When the value of the status is changed from New to In-Progress, a new layout is shown with a rich text control that lets the user provide information on the status progress.
When the user finishes editing the work item and clicks Submit, the confirmation page shows with success or failure message.
To show the updated task detail page, click Return to Home.
To implement the functionality:
Decide which UI control to use as the action source to trigger dynamic UI change, and which listener to control the UI interaction.
Define new UI regions in the work item UI layout meta data file.
Implement the corresponding listener in managed bean.
Implement API
getUIRegionName() to return different UI region based on different condition.
Register the managed bean in the connector's
tpc-config.xml file.
Use the bean in the UI metadata through EL expression.
The following sections provide more detail using the sample connector.
The sample connector uses the combination box control for the "status" field as the action source. It also uses the
PopupMenuListener on the combo box control to listen to the selection change and to do dynamic update UI work. It also uses the Submit button to navigate between the task detail page and the confirmation page layout.
The configuration detail is in the
SampleDef.xml file. Note in the following example how the status combination box and submit action are defined with their corresponding attribute name and value pairs.
Example 4-14 UI control and listener attribute selection
<?xml version="1.0" encoding="windows-1252" ?> <region id="Homepage"> <formLayout columns="1" blockSize="10" fieldWidth="400" labelWidth="60"> <inputText label="#{workitemmodel.labels.PARENT_TASKID}" value="#{workitemmodel.values.PARENT_TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.TASKID}" value="#{workitemmodel.values.TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.DESC}" value="#{workitemmodel.values.DESC}"/> <listOfValues label="#{workitemmodel.labels.OWNER}" value="#{workitemmodel.values.OWNER}" source="OWNER" pprTargets="statusID"/> <comboBox label="#{workitemmodel.labels.STATUS}" value="#{workitemmodel.values.STATUS}" id="statusID" valueSet="#{workitemmodel.listItems.STATUS}" readOnly="true" popupMenuListener="#{mainBean.statusListener}"/> <inputDate label="#{workitemmodel.labels.DUEDATE}" value="#{workitemmodel.values.DUEDATE}"/> <inputText label="#{workitemmodel.labels.URL}" value="#{workitemmodel.values.URL}"/> <panelLayout> <action text="Submit" actionCommand="gotoc actionListener="${dynamicBean.actionListener}"/>onfirmpage" </panelLayout> </formLayout> <separator/> </region>
In addition to the default
HomePage region, this code creates two new regions: region "Demo" (shown when status is changed to "in-progress") and region "confirmation" (shown when the user clicks Submit).
Example 4-15 New region definition
<region id="Demo" helpTopicId="f1_connector_sample_htm"> <formLayout columns="1" blockSize="10" fieldWidth="400" labelWidth="60"> <inputText label="#{workitemmodel.labels.PARENT_TASKID}" value="#{workitemmodel.values.PARENT_TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.TASKID}" value="#{workitemmodel.values.TASKID}" readOnly="true"/> <inputText label="#{workitemmodel.labels.DESC}" value="#{workitemmodel.values.DESC}"/> <listOfValues label="#{workitemmodel.labels.OWNER}" pprTargets="statusID" value="#{workitemmodel.values.OWNER}" source="OWNER"/> <comboBox label="#{workitemmodel.labels.STATUS}" value="#{workitemmodel.values.STATUS}" popupMenuListener="#{mainBean.statusListener}" valueSet="#{workitemmodel.listItems.STATUS}" readOnly="true" id="statusID"/> <inputDate label="#{workitemmodel. ��labels.DUEDATE}" value="#{workitemmodel.values.DUEDATE}"/> <inputText label="#{workitemmodel.labels.URL}" value="#{workitemmodel.values.URL}"/> <textEditor label="#{workitemmodel.labels.STATUS_REPORT}" value="#{workitemmodel.values.STATUS_REPORT}" contentType="html"/> <panelLayout> <action text="Submit" actionCommand="gotoconfirmpage" actionListener="${dynamicBean.actionListener}"/> </panelLayout> </formLayout> </region> <region id="confirmation"> <panelLayout layout="vertical"> <inputText value="Task has been updated successfully." readOnly="true"/> <action text="Return to Home" actionCommand="gotohomepage" actionListener="${dynamicBean.actionListener}"/> </panelLayout> </region>
The listener object on the status combo box (
popupMenuListener) is implemented in
HomePageBean.java as follows:
Example 4-16 Implementing a listener in a managed bean
public PopupMenuListener getStatusListener() { if (statusListener == null) { statusListener = new PopupMenuListener() { public void popupMenuWillBecomeInvisible(PopupMenuEvent e) { JComboBox src = (JComboBox) e.getSource(); Object[] selected = (Object[])src.getSelectedItem(); if(selected == null) return; String value = (String)selected[1]; if (value != null && value.contains("Progress")) { _rcontext.getConnectorParams().put("navigatorpage", "D"); } else _rcontext.getConnectorParams().put("navigatorpage", "H"); //we just need to refresh the current page; ViewManager vm = ViewManager.getInstance(); if(vm != null) vm.refreshWorkItemDetailUI(_rcontext); } public void popupMenuCanceled(PopupMenuEvent e) { } public void popupMenuWillBecomeVisible(PopupMenuEvent e) { } }; } return statusListener; }
The listener object on the Submit button (
actionListener) is implemented in the
DynamicRegionBean as follows:
Example 4-17 Implementing listener on Submit button
public ActionListener getActionListener() { if (actionListener == null) { actionListener = new ActionListener() { public void actionPerformed(ActionEvent event) { String command = event.getActionCommand(); ViewManager vm = ViewManager.getInstance(); if (command != null && command.equals("gotohomepage")) { _rcontext.getConnectorParams().put("navigatorpage", "H"); } else if (command != null && command.equals("gotowelcomepage")) { _rcontext.getConnectorParams().put("navigatorpage", "W"); } else if (command != null && command.equals("gotodemopage")) { _rcontext.getConnectorParams().put("navigatorpage", "D"); } vm.refreshWorkItemDetailUI(_rcontext); } }; }
All managed beans should implement the
AlmScope interface. Oracle Team Productivity Center uses
AlmScope to synchronize the
renderingContext and the corresponding
AlmComponent for the UI control that uses the managed bean.
There are two ways to pass information from connector Managed Bean layer so it can be used in other connector classes:
Parameter name value pairs can be put at the connector session level. To review the code shown in the previous example:
Example 4-18 Parameter name value pairs at connector session level
_rcontext.getConnectorParams().put("navigatorpage", "H");
This information can be retrieved inside other connector classes as shown here:
Through the current work item object
The current work item object can be accessed through the
ViewManager class:
Example 4-20 Accessing work item through ViewManager class
public WorkItem getCurrentWorkItem(RenderingContext rcontext);
Inside the managed bean class, you can modify the work item's submit values. Then other connector classes can use it to process logic based on different field values.
ViewManager APIs to refresh the work item detail page.
Example 4-21 Refreshing the work item detail page
public void refreshWorkItemDetailUI(RenderingContext rcontext);
This API triggers the call to
getUIRegionName(), which returns new region name based on connector parameter or work item field values. For example, the sample connector uses a parameter to return a new region name:
Example 4-22 Using a parameter to return a new region name
public String getUIRegionName(Map session, String wiType, WorkItem workItem) throws ALMException { String region = ""; Map params = (Map) session.get(WorkItemConnector.SESSION_PARAMS_KEY); if (params != null) { Object val = params.get("navigatorpage"); if (val == null || val.equals("H")) region = "Homepage"; else if (val != null && val.equals("W")) region = "Confirmation"; else if (val != null && val.equals("D")) region = "Demo"; } return region; }
Register the managed bean
DynamicRegionBean with the name
UIBean inside the file
tpc-config.xml as follows:
Example 4-23 Registering the bean class in tpc-config.xml
<?xml version="1.0" encoding="windows-1252" ?> <!-- TPC Configuration file --> <tpc-config version="188.8.131.52.0" xmlns="http://fusion.oracle.com/tpc"> <managed-bean> <name>mainBean</name> <impl-class>oracle.sampleconnector.view.mbean.HomePageBean</impl-class> <lifecycle>page</lifecycle> </managed-bean> <managed-bean> <name>dynamicBean</name> <impl-class>oracle.sampleconnector.view.mbean.DynamicRegionBean</impl-class> <lifecycle>page</lifecycle> </managed-bean> <managed-bean> <name>compBean</name> <impl-class>oracle.sampleconnector.view.mbean.ComponentBean</impl-class> <lifecycle>page</lifecycle> </managed-bean> </tpc-config>
On a work item detail page, the connector writer can create a link that, when clicked, opens a new Team Productivity Center-specific editor. For example, a Bugzilla bug has a field "Depends On," which may hold a bug number for another bug. The Bugzilla connector writer can create a link on the label. When clicked, a new editor opens up inside JDeveloper showing the details of that bug.
Team Productivity Center uses
alm as the resource protocol and supports these URL formats:
Work item
Team query
alm:/reposName/workitemType/Team Queries/queryName.wiq
User query
alm:/reposName/workitemType/My Queries/queryName.wiq
Generic page
Note that for a generic page, the connector writer needs to do the following:
Put UI page files directly under the
/META-INF/pages folder in the connector source code tree. This is because
/META-INF/pages is set as the default
DOC_HOME in the TPC framework.
repository=reposName as a parameter to the URL.
For example, if the URL used in the sample connector is
alm:/component/component.tpcx?repository=SampleConnector&component=inputDate, then there should be a
component.xml file under the
/META-INF/pages/component folder.
To open a new editor:
Using these URLs, there are two different ways to open a Team Productivity Center-specific editor:
OpenTPCPageInEditor () API on
Example 4-24 Using the OpenTPCPageInEditor() API
ViewManager vm = ViewManager.getInstance(); vm.OpenTPCPageInEditor("/component/component.tpcx? repository=SampleConnector&component=inputDate");
Similarly, this will open a specific work item editor:
Use the
WebResource tag
Using the sample connector as an example, there is a field "Parent ID" where its value portion is a link. When clicked, the work item editor for the parent task opens up. To achieve this, follow these steps.
Use the
WebResource tag to define the field that can generate the URL in connector definition file:
Example 4-26
<RepositoryModel resName="res" resFile="/META-INF/res/modelresource.xml"> <WorkItem type="Task" webURLHandler="oracle.sampleconnector.SampleConnectorService"> <Fields> <Field name="PARENT_TASKID" label="${res.PARENT_TASK_ID}" type="number" readOnly="true"/> <Field name="TASKID" label="${res.TASK_ID}" type="number" readOnly="true"/> <Field name="DESC" label="${res.TASK_DESC}" required="true" maxLength="80" type="string"/> …… <Fields/> <WebResource> <URLDef name="PARENT_TASKID" archorOn="label"/> …… </WebResource> …… <WorkItem/> <RepositoryModel/>
The valid values for the attribute
archorOn are "label" and "value". If the attribute value is "label" the field label becomes a hyperlink. Otherwise the value acts as a hyperlink.
Implement the
getURL() API on
WorkItemFieldFeature interface
SampleConnectorService implements the method on this interface. The
getURL() method constructs the URL for the parent task field.
Example 4-27
public URL getURL(Map session, String attrName, Object attrValue, WorkItem wi) { String urlString = ""; if (attrName.equalsIgnoreCase("PARENT_TASKID")) { Integer taskid = (Integer) attrValue; String reposName = (String)session.get("repositoryName"); String wiType = (String)session.get("wiType"); if(reposName != null && wiType != null) urlString = "alm:/" + reposName + "/" + wiType + "/" + taskid + ".wid"; } try { return new URL(urlString); } catch (MalformedURLException e) { System.out.println(e); } return null; }
In the connector definition file, find the work item section and put the class name as the value for attribute
webURLHandler. See the sample code in the first bullet.
When the value for
anchorOn is set to "label", the UI metadata for the corresponding work item field should be set to an "input" field, such as
inputDate, or
When the value for
anchorOn is set to "value", the UI metadata for corresponding work item field should be set to read-only
Once you have developed your connector, you will want to be able to run your connector inside of the debugger during execution. This capability is built into your project already.
To run your connector inside the JDeveloper debugger:
Right-click on your built/deployed project and select Debug Extension.
This launches another copy of JDeveloper from which you can open up Team Productivity Center and connect to an Oracle Team Productivity Center Server that has your connector defined. Then you can set breakpoints in your Java code and step through it while using watch windows for variables and use standard debugging utilities.
Once you have developed a connector for use with Oracle Team Productivity Center, there are a number of tasks left to perform. One important task is to handle errors that occur while using the connector. Oracle Team Productivity Center has two ways of propagating errors and messages to the client; they are described here.
You may choose to include help files with your connector, to provide assistance for your team members in using the connector you have developed. You can then view your help in the JDeveloper online help browser or in an external help viewer.
In addition, you will need to package your Oracle Team Productivity Center connector so that it can be downloaded by other team members. This includes compressing the connector into a JAR file and a bundle file. Furthermore, any help files you have created for the connector need to be included in the JAR file.
Oracle Team Productivity Center provides two ways to propagate errors and messages to the Team Productivity Center client:
ALMException used on interface methods
ALMMessage used to queue to
All interface methods throw
ALMException when something serious happens inside a connector. You can put an appropriate warning or message with the runtime instance of
ALMException. The client framework will show to it the end user.
Example 4-28 Error handling
try { connector.hasDynamicUI(session); } catch(ALMException e) { setLastError(e); }
You can also use the classes provided in package oracle.alm.common.message to propagate error messages to the client. Two classes are defined in this package.
Table 4-7 Class Summary
Manages the connection to the backend repository.
AlmMessageFactory is the class for message registration and access through Team Productivity Center. Use this class and
AlmMessage to log any messages to be reported to the client through the UI framework.
AlmMessageFactory is implemented as a singleton. To get an
AlmMessageFactory, call:
AlmMessageFactory msgFactory = AlmMessageFactory.getInstance()
To add a message, call
AlmMessageFactory.addMessage() by passing the
messageID and the associated message string.
You can add custom help files, including context-sensitive help, to an Oracle Team Productivity Center connector. Your users can then access any information they need to help with the operation of setup of your connector.
There are two ways to display connector specific help pages to the users of your connector. The first approach is to show these help pages inside JDeveloper Help Center. The second approach is to show these pages in their own frame on the client's desktop or in a Web browser.
Extensive help is available for the writer of help for a JDeveloper extension, such as the Team Productivity Center connector, in the Developing Help Extensions topic.
You can write and display connector-specific help inside the JDeveloper Help Center for your users to refer to. If you implement JDeveloper help as an JDeveloper Help extension, your users will be able to access this help by pressing the F1 key while viewing a dialog in your connector.
To include help for a Team Productivity Center connector:
Provide F1 help files in HTML format for each page that shows in JDeveloper. They should be located in a folder
/Help inside the packaged connector JAR file.
Create a new JDeveloper extension that only contains these help files.
Add the connector help ID to the connector UI definition XML file.
You may choose to present the help for your connector in an external viewer, such as the user's default Web browser or a PDF viewer.
To present connector help in an external viewer:
Provide F1 help files in HTML format for each page that shows. They should be located in a folder called
/Help in the packaged connector JAR file.
Create a new JDeveloper extension that only contains these help files.
Add a Help button in the work item detail UI. This can be done by adding a toolbar and one help button on this toolbar in the connector UI definition XML file:
Implement the listener object class.
The final phase of preparing an Oracle Team Productivity Center connector is to package it in JAR files for installation as a JDeveloper extension. This allows you to install the connector on the Team Productivity Center server so that your team members can connect to the repository to which this connector applies.
In order to install your connector onto the server, and so it can be installed as an extension into JDeveloper, it must be packaged correctly. There are three pieces to the packaging:
The JAR file that will contain your connector and all of its required files.
A separate JAR file containing your help files and their required files.
A bundle in ZIP format that will contain the two previous JAR files plus a
bundle.xml file to describe how JDeveloper can install this as an extension.
You can create deployment profiles inside of your project to generate all of these files for you.
Before you create any deployment profiles, ensure you have built the project successfully and all output files have been created in the correct directories.
The connector JAR file contains all the components of your connector that will be included in the extension dedicated to your connector.
To generate the connector JAR file:
Double-click on your project in the Application Navigator and select Project Properties > Deployment.
Click New.
Select JAR File as your archive type, and then enter a name for your JAR file. Typically this is
Connector<your connector name>.JAR
In the Edit JAR Deployment Profile Properties dialog, select Filters. Select all files in the META-INF directory (except
Bundle.xml, to be defined soon) and all the files in your package directory.
Click OK.
To test your connector JAR deployment, right-click on your project and select Deploy > <your deploy profile> > to JAR File.
The Help JAR file will contain everything needed to include Help with your connector extension. JDeveloper extension tools provide an integrated process for generating connector Help JAR files.
To generate a connector Help JAR file:
Double-click on your project in the Application Navigator and select Project Properties > Deployment.
Click New.
Select JAR File as your archive type, and then enter a name for your help JAR file. Typically this is
Connector<your connector name>Help.JAR
In the Edit JAR Deployment Profile Properties dialog, select Filters. Select all the help-related files or the directory those are stored in. Deselect all other files.
Click OK.
To test your connector JAR deployment, right-click on your project and select Deploy > <your help deploy profile> > to JAR File.
When the connector JAR file is constructed, you can then prepare to deploy it by generating a bundle file. This is a ZIP file, which you can use to install the connector extension.
To generate a connector bundle file:
Double-click on your project and select Project Properties > Deployment.
Click New.
Select JAR File as your archive type.
Uncheck Include Manifest.
Enter a name for your bundle ZIP file.
This is typically located in a Bundle folder at the same level as your Deploy folder, and called
Connector<your connector name>Bundle.ZIP. Be sure to name it .ZIP instead of .JAR.
In the Edit JAR Deployment Profile Properties dialog, expand the Project Output node, then select Filters.
Rename this to file group to JAR Output. Change the Target Directory in Archive to:
oracle.teamproductivitycenter/connectors/<your connector name>. There should be no .JAR at the end. This is the path inside of the ZIP file to extract this file to
The installers are case-sensitive, so make sure the case is correct for your file paths.
Go to the Contributors node under the JAR Output file group. Click Add and add the location where your connector JAR and help JAR files are generated.
Go to the Filters node under the JAR Output file group. Select the connector and connector help JAR files you already generated
Select the File Groups node and click New. Create a new file group called Bundle Output.
Go to the Filters node under the Bundle Output file group and deselect everything except for your bundle.xml file. Make sure the Target Directory in Archive edit box is blank.
Go to the Profile Dependencies node and add the connector and the help deploy profiles as dependencies.
Click OK.
To test your connector bundle ZIP deployment, right-click on your project and select Deploy > <your bundle profile> > to JAR File. This creates a new ZIP file that contains your connector JAR, the help JAR and the
bundle.xml file.
The bundle.xml file describes what is in an extension and what its dependencies are. It also holds the version information and info about the author.
Example 4-31 Connector bundle file bundle.xml
<update-bundle version="1.0" xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle" xmlns:u="http://xmlns.oracle.com/jdeveloper/update"> <u:update id="oracle.teamproductivitycenter.sampleconnector"> <u:name>Oracle Sample Connector</u:name> <u:version>1.0</u:version> <u:author>Oracle Corporation</u:author> <u:author-url>http://www.oracle.com</u:author-url> <u:description> Sample connector for Oracle Team Productivity Center </u:description> <u:requirements> <u:requires-extension id="oracle.jdeveloper" minVersion="188.8.131.52.00" maxVersion="188.8.131.52.99" /> <u:requires-extension id="oracle.teamproductivitycenter" minVersion="220.127.116.11.00" maxVersion="188.8.131.52.99" /> </u:requirements> </u:update> </update-bundle>
Oracle Team Productivity Center provides support for connectors to show appropriate UI based on the running JDeveloper locale. As seen in the work item UI and model definition XML files, a resource file can be used to store localized strings. For example, if JDeveloper is running in JPN locale, the user may want to see connector detail page in the same locale. To support this, you can create language-specific resource bundle files. Example 4-32 is an example for the
Example 4-32 Internationalization file modelresource.xml
<?xml version="1.0" encoding="ISO8859-1" ?> <resources xmlns="http://xmlns.oracle.com/bali/rts/tpc" package="company.bugzilla.res"> <resource key="MSG_SAVEBUG_TITLE">BugDB: Save A Bug</resource> <resource key="MSG_NEWBUG_TITLE">BugDB: Create A Bug</resource> <resource key="MSG_BUGAPI_ERROR">Bug API Error: </resource> <resource key="DESCRIPTION">Description</resource> <resource key="BUG_NAME">Bug </resource> <resource key="BUG_NO">Bug Number</resource> <resource key="BUG_BASEBUG_NO">Base Bug No</resource> <resource key="BUG_STATUS">Status</resource> <resource key="BUG_SUBJECT">Subject</resource> <resource key="BUG_PRODUCT">Product</resource> <resource key="BUG_PRIORITY">Severity</resource> <resource key="BUG_COMPONENT">Component</resource> <resource key="BUG_SUBCOMPONENT">Sub Component</resource> <resource key="BUG_ASSIGNEE">Assigned</resource> </resources>
And here is an example of the file
Example 4-33 Internationalization file uiresource.xml
<?xml version="1.0" encoding="ISO8859-1" ?> <resources xmlns="http://xmlns.oracle.com/bali/rts/tpc" package="company.bugzilla.res"> <resource key="COMMMENTS">Comments</resource> <resource key="ADD_COMMENTS">Add Comments</resource> <resource key="UPDATE_COMMENTS">Update Comments</resource> </resources>
If JDeveloper is running in Japanese, the framework looks for resource bundle files named
modelresource_jp.xml and
uiresource_jp.xml to find and display labels in Japanese. You can create these files and put them in a central location. Store these resource bundle files under the folder
META_INF\res in the connector jar file.
This chapter describes the basic operations of Oracle Team Productivity Center, including logging in, connecting and disconnecting, selecting your team, and using and interpreting the build summary.
This chapter includes the following sections:
Section 1.2, "Connecting to Oracle Team Productivity Center"
Section 1.4, "Understanding the Build Dashboard and Build Summary"
Oracle Team Productivity Center is a Oracle JDeveloper feature that provides access to a set of application lifecycle management (ALM) tools and technologies.
ALM tools address the need to integrate the growing number of data tracking and data repository tools that are used by product development organizations throughout the product's lifecycle. Initial product development, for example, typically tracks product definition and specifications, as well as defects discovered during initial testing. As the product is released, customer requests and enhancements may be tracked in a third repository. When developers are later required to maintain a customer-released product in one development branch while also doing new feature development for upcoming releases in a different branch, the request and defect-tracking repositories need to be linked with the appropriate development branch, whether maintenance or new release, of the team's version-control system. Oracle Team Productivity Center lets teams integrate all these repositories, and any others they may use, directly in the integrated development environment.
In addition to bringing external data repositories into the IDE, Oracle Team Productivity Center supports a highly flexible hierarchy of teams and subteams that can be configured and maintained by local team administrators. Oracle Team Productivity Center is designed to:
Increase value in existing investments by providing unified access to current artifact repositories (including bug databases, version repositories, and other content libraries) and allowing integration between them.
Allow for quick and flexible assembly of teams and subteams.
Collaborate with other team members through chat.
Reduce the barriers between different teams during the development process, and eliminating many hard-wired boundaries through collaboration, shared labeling, and smooth information flow.
Maximize current investments in skills, processes and technologies.
Increase flexibility by reducing the time it takes to integrate new applications into the development team environment.
Oracle Team Productivity Center also presents information about the latest builds undergoing development. A build dashboard and build summary present at-a-glance information about the status of development builds, with links to let you quickly find the details of issues that interest you in the latest build.
When you install the latest version of Oracle JDeveloper containing Oracle Team Productivity Center, you have the option of migrating files from a previous version. If you have already been using Team Productivity Center and are upgrading to a new version, be sure to follow the installation instructions for migrating to the latest version. In particular, be sure to install and migrate to the newest versions of any connectors you use. This will ensure that you have the latest capabilities, and that your connectors are fully compatible with the latest Team Productivity Center client.
Oracle Team Productivity Center is made up of three parts:
The Oracle Team Productivity Center client software.
The Oracle Team Productivity Center server software, which is available from Oracle Technology Network. The server software includes a standalone installation guide, also available from Oracle Technology Network, which includes help on installing the Oracle Team Productivity Center server and connectors
Oracle Team Productivity Center connectors, which are available by selecting Help > Check for Updates. Connectors permit the Oracle Team Productivity Center client software, running inside JDeveloper, to interact with data repositories such as bug-tracking systems and feature databases.
To connect to the Oracle Team Productivity Center server:
View > Team Navigator
This opens the Team Navigator. Click on Connect to Team Server to continue.
For more information on installing connectors from Check for Updates, see the "How to Install Extensions with Check for Updates" section in the Oracle Fusion Middleware User Guide for Oracle JDeveloper.
When you initially log into Team Productivity Center, you will need some information provided by your administrator.
Table 1-1 Productivity Center Login Options
Team Server
The machine name or IP address of your Oracle Team Productivity Center Server.
The dedicated port used by your Team Server.
Use SSL
Select this if your Team Server connection requires a secure socket layer connection.
The username assigned to you by the Oracle Team Productivity Center administrator.
The password assigned to you by the Oracle Team Productivity Center administrator. To change this password, select Manage Profile after logging in with your existing password.
Remember Connection Information
With this option selected, you will only need to enter your password when logging in the future. Team Productivity Center will retain all other information about your connection (server, port, and username).
Connect Automatically
With this option selected, you will be connected to Oracle Team Productivity Center every time you open JDeveloper.
You can disconnect from Team Productivity Center at any time.
To disconnect from Team Productivity Center:
Click the dropdown on the right-hand side of the currently selected team.
Select Disconnect from Team Server.
Team Productivity Center disconnects automatically when you quit JDeveloper.
Your Oracle Team Productivity Center user profile contains your first and last name, your email, and your Oracle Team Productivity Center password. On the Manage User Profile dialog, you can also set Oracle Team Productivity Center to remember your password on future connections.
To set values in your user profile:
From the Team Navigator menu, select Manage Profile.
Update any of your user information in the name and email fields in the upper part of the dialog.
To change your password, enter your old password, then enter your new password twice, once in the New Password field, then a second time to confirm in the Retype Password field.
If you would like Oracle Team Productivity Center to remember your password for future connections, select Remember Password.
Click OK.
When using Oracle Team Productivity Center, you will often be accessing information stored in data repositories, many of which require you to have a user account for access. For example, if you have an account in your organization's bug tracking database, you need to provide this information to Oracle Team Productivity Center so that you can view, edit and save bug report information inside Oracle Team Productivity Center.
Oracle Team Productivity Center can store your account information (user ID and password) to simplify access to these accounts while working. For more information about work item repositories, see Section 2.2, "Working With Work Items."
To manage your repository accounts:
From the Team Navigator menu, select Manage Accounts.
From the left-hand pane of the dialog, select the work item repository for which you need to change your account information.
In the right-hand pane of the dialog, enter the up-to-date information for the account associated with the selected repository.
You can optionally verify that your user ID and password are correct for the account you are editing. To do this, click Test Connection. The result of the test is displayed in the Status box.
When you have verified that the information is correct, click OK.
Navigating Oracle Team Productivity Center involves viewing team members, browsing versioning repositories and viewing or querying work items. You can also select your team and chat with team members.
You navigate Team Productivity Center through the Team Navigator.
To use the Team Navigator:
Select View > Team > Team Navigator.
Within the Team Navigator, additional accordions display the various components and interfaces of Team Productivity Center:
At the very top of the Team Navigator accordion, Oracle Team Productivity Center displays a drop-down list of teams. Once you select a team from this list, the three accordion panels below display data for the selected team and its members.
Displays the members when you select a given team.
Displays work item repositories connected for the selected team. When you connect to a repository, you can create queries to that repository. For more information about work items and repositories, see Section 2.2, "Working With Work Items."
Displays the connected versioning repositories for the team. You can check out files from your versioning repository to your project/application (depending on the versioning system). You can view versioned files in read-only format. You can perform some repository administration tasks (such as create new directories), depending on the versioning system.
When you connect to your Team Productivity Center server, Oracle Team Productivity Center displays a list of the teams to which your administrator has added you.
Once you have signed into Team Productivity Center, you can select from any available teams. (In some cases, you may only be a member of a single team, in which case no selection options will appear.)
To select a team:
Click on the dropdown list just below the Team Navigator title.
Select a team.
You will notice that a list of team members including yourself appears. Below the Team Members accordion, you will see the Versioning and Work Items accordions. Each of these will provide access to information repositories needed by your team.
Oracle Team Productivity Center displays the online and chat status of team members. In addition, rolling the cursor over a team member's name displays that member's data: full name, their role in the team currently being displayed, and their email address. Click the right mouse button on the team member's name to display the following options:
Send Email
Opens a message in your system's default mail tool.
Initiates chat with the member. If you have not yet selected a chat application or server, Oracle Team Productivity Center displays the Connect to Chat Server dialog.
Once you have installed Team Productivity Center, you can chat with members of your team.
To connect to Oracle Team Productivity Center chat:
Select View > Team > Chat.
You can initiate a chat session in two ways:
Click the chat symbol adjacent to the Team Members accordion header.
Double-click on the name of any team member.
When you initiate a chat in Oracle Team Productivity Center you will have two groups available for chat:
Buddies from your active XMPP/Jabber protocol.
Teammates from the currently selected team, visible in the members accordion only.
Although you can only connect to one chat server at a time, you can also create a new connection to a different chat server and select it as your active server.
Once you have installed Team Productivity Center, you can use Chat by selecting View > Team > Chat at any time. You don't have to be connected to Team Productivity Center to do so: you can open the chat window at any time, regardless of whether you are connected to Team Productivity Center. However, you cannot start a chat from the Team Productivity Center navigator if you aren't connected.
To create a new chat server connection:
Disconnect from your current server. You can either use the Disconnect button, or select the connection from the list, then click the right mouse button and select Disconnect.
Right-click on the empty Buddies node, then select Connect.
You can also click the Edit Connection Property button, or click the Connect toolbar button. Any of these will open the Connection Property dialog, from which you can click the Connect button.
Enter the settings for your new chat server.
Oracle Team Productivity Center only supports XMPP/Jabber protocols, and does not support multiple connections. The first time you log into the Team Member chat panel you may be asked to provide some configuration information needed by Oracle Team Productivity Center. Table 1-2 contains the information that is typically included.
Table 1-2 Configuration Options
The name of the host chat server URL.
The assigned port number.
The assigned domain.
User Name
Your chat server user name.
Your chat server password.
Remember Password
(dependent on chat server configuration)
Connect when JDeveloper starts
(dependent on chat server configuration)
Depending on the configuration of your chat server, the last two options may or may not work automatically.
In addition, two buttons in the Chat pane toolbar provide a shortcut to connecting or editing the connection properties:
Connects to chat server. Uses same fields as Edit Connection Properties.
Once you are connected, the Chat window displays two buttons on the toolbar of a chat that is in progress: Send, which sends the chat message, and Clear, which deletes all the text.
Edit Connection Properties
Displays Connect to Chat Server dialog, which allows you to specify the following properties for your chat connection and connect to the server.
The URL for your selected chat server. Disconnect from any previously connected server before choosing this one, either for Connect or for Edit Connection Properties
The port on the chat server dedicated to chat.
The top-level domain (for example, mycompany.com) used to host the chat server.
Your username in the chat server you are selecting or specifying.
The password associated with the username in the preceding field.
Remember Password
Save this password for future chat sessions. Selected automatically if you also select Connect When JDeveloper Starts.
Connect When JDeveloper Starts
Automatically connect to this chat server each time you start JDeveloper. Use this to specify the default chat server.
In addition, the Chat window contains four other buttons for controlling the chat:
Table 1-3 Chat window control buttons
When connected, clicking this button disconnects from the current chat server. When disconnected, this button opens the Connect to Chat Server dialog.
Displays a drop-down menu with the following options:
Show Offline Buddies
Show Empty Groups
Show Details
Add Group
Add Buddy
Displays a drop-down menu from which you can select from the server's available list of status messages (for example, Away, Available, In a Meeting, and others depending on the chat server). The message you select is displayed for other team members who view your icon in their chat window.
Edit Connection Properties
Opens the Edit Connection Properties dialog.
The Build Dashboard and Build Summary summarize the builds of projects your organization is tracking with Team Productivity Center. When you first log in to Team Productivity Center, JDeveloper displays a temporary snapshot of the Build Summary, containing information about the development/build branches your team is following, with the most recent builds and links to other results.
The Build Dashboard presents detailed statistics from builds of projects your organization is tracking with Team Productivity Center. The upper portion of the summary gives an overview of build information, test results, and the total work items represented in the build. The lower portion shows related transactions from the source control management system in use, if Oracle Team Productivity Center was used to commit to the source control management system. You can open the build summary for a specific build listed in the Build Dashboard to view additional details on that specific build.
If the Build Dashboard is not visible, you can access it from the View menu.
To open the Build Dashboard:
View > Team > Build Dashboard
If you have not yet logged in to Oracle Team Productivity Center and you select the Build Dashboard, you will be asked to log in to Oracle Team Productivity Center first.
To use the Build Dashboard:
Clicking the branch name or the Total Transactions links of a row in the Build Dashboard displays the build summary window. This shows statistics from builds of projects your organization is tracking with Team Productivity Center.
Once you display the Build Dashboard, you can select from the latest builds and then view the information shown in Table 1-4.
Table 1-4 Build Dashboard Options
Click the dropdown to select the development branch you are interested in.
The sequential list of builds in the selected branch. Click on the build of interest to display the Build Summary for the selected build.
Below the list of builds in a branch, the Build Dashboard displays a list of related transactions for the selected build in the selected branch.
Related Transactions
The Build Dashboard displays the Change Set, Change Set Owner, Repository, Type, and Key for the selected branch. Of these, the Change Set and Key can be selected; the other display elements are read-only.
Change Set
The change set in the selected versioning system. Selecting an individual change set loads it into the Log window and displays elements assigned to the change set you have selected
Displays the work item associated with the change set being displayed. Select the work item to view and modify it.
All build/test system configuration takes place when the plug-in is installed in the build/test environment, typically when Oracle Team Productivity Center is installed initially. After installation and configuration, build/test system results are returned to the Team Productivity Center client and made available to the Build Dashboard. You can customize the dashboard to display the results that are of interest to you.
To customize the build dashboard display:
Click on the Branch drop-down from the Build Dashboard, then select Customize.
This opens the Manage Module and Display Notification dialog. From this dialog you can select the modules you wish to include in the dashboard, as well as whether you choose to subscribe to notification in JDeveloper when one of these modules is updated. For more information while using the Manage Module and Display Notification dialog, press F1 or click Help at any time.
From the build dashboard, you select one of the available builds about which you wish to find out more information. This displays the Build Summary for the selected build
To select a build from the Build Dashboard:
Click on the Branch drop-down from the Build Dashboard, then select the build of interest.
The Build Summary presents statistics from one specific build your organization is tracking with Team Productivity Center. The upper portion of the summary gives an overview of build information and test results represented in the build. Table 1-5 contains Build Summary options, including detailed information about a given build with work item and owner information.
Table 1-5 Build Summary Options
Select the statistics that you want the Build Summary to display:
All Tests
Show the results of every test, including pass and fail results.
Errors Only
Show only the results of tests that contain errors.
Failures Only
Show only the results of tests that fail.
Errors and Failures
Show the results both of tests with errors and also tests with failures.
Successes Only
Show only the results of successful tests.
Next to the statistic drop-down list, the Build Summary gives you the following ways of altering what information is displayed.
Unassigned Only
If you check this box, the Build Summary will display only selected results (as determined by the statistics selected in the Show box) that have no assigned owner. Leave the box unchecked to display all results.
Display selected results filtered by category and by a string. Click the binocular drop down, then select the area from which you wish to filter the results. You can choose to filter results from one of these categories: Module, Class, Test case, Owner, or Work Item.
For example, when you have selected the category, type a string you wish the Build Summary to use as a search filter. The Build Summary displays only results that match the filter string
You can expand and collapse any of the individual results in the Build Summary by clicking the node icon at the left of the results in the Class column. You can also expand and collapse all results by clicking the Expand All (the double-plus sign icon) and Collapse All (double-minus sign icon) buttons next to the Filter field.
Below the overview, the Build Summary provides detailed information about the module, class and tests performed, as well as links to the repositories your team is using to track bug information. The summary contains the following columns:
The name of the test class run on the build. You can expand or collapse the hierarchical view of members in this class by clicking on the + or - sign at the left of the class name, or you can expand and collapse all classes by using the Expand All and Collapse All icons at the top of the display.
Tests Run
The number of tests run in each class. If you expand the class, the summary displays the number of tests run for each member in the class as well as the total number of tests run in the class
The number of tests in each class that resulted in a failure.
% Passed
The percentage of successful tests. Note that the percentages in each row reflect the ratio of passes to failures for each member of the class; if you collapse a row (which suppresses the display of elements in, and beneath, that class member), the percentage passed may not appear to reflect the visible numbers until you expand the row.
A graphical display representing the status of each test, as a success, a caution, or a failure.
The Results column displays a link to a detailed screen of information which summarizes the results of a test, including the specific error messages or output produced by that test. For failed test cases, this column normally displays more data, such as a full stack trace. Click the link to display a read-only dialog with full data.
The assigned team member responsible for the test on the selected row. You can send the owner email or open a chat session with the owner by right-clicking the owner's name.
If no owner is assigned to a test, the owner field contains a button you can use to assign yourself as the owner. Tests without an assigned owner will be the only items displayed if you select the Unassigned Only checkbox.
Additionally, this cell contains a toggle button: Add me as a owner and Remove me as a owner. To take ownership of a failed test, click Add me as a owner. To relinquish ownership, click Remove me as a owner.
Work Items
The numbers of any Oracle Team Productivity Center work items assigned to the test. Click on the work item number to display the details of that work item.
To show all repositories the team can access, click Create Work Item. This displays a list of all the work item repositories available to that team. You can then create the appropriate work item for that test.
Once the new work item is saved, the build summary page is updated with the new work item number.