IBM Engineering Workflow Management
- Last updated
- Save as PDF
Overview
IBM Engineering Workflow Management (EWM) (formerly Rational Team Concert) includes work-item, build, and software configuration management along with planning tools, dashboards, and reports. Many organizations use EWM as their planning and reporting center. However, when members of the extended software development and delivery tool adopt specialist tools, the reports from EWM no longer reflect up-to-the-minute data.
For example, if the testing team chooses to use Micro Focus ALM/Quality Center as their test and defect tracking solution, the development team needs access to the information in the defect tracker to triage bug reports. Or, if the business analysts use a purpose-built requirements management tool such as DOORS, DOORS Next, or Jama, the developers using EWM would prefer to see these reflected as stories in EWM. And if one development team uses Jira to manage their work, the collaboration between the teams using EWM and these other tools is fractured.
Planview Hub addresses this by synchronizing work items in EWM to defects, tasks, stories work items and other artifacts in other lifecycle tools.
Key Features and Benefits
- Synchronizes artifacts across the lifecycle, allowing information to flow freely between EWM and other tools
-
Uses Artifact Relationship Management to automatically sync complex containment structures (like folders) and relationships between artifacts (like “Parent/Child”, “Tested by” or “Blocked by”) between EWM and any other tool we connect to
-
Use our OSLC rich hover support, combined with Artifact Relationship Management, to get instant visibility to any tool we connect to, directly in EWM
- Improves team collaboration by connecting EWM to third party tools and allow artifacts to be synchronized across the lifecycle
- Supports cross-tool traceability and reporting, removing the need for manual processes and spreadsheets
- Enriches the reports in EWM to include up-the-minute status from other tools
Common Integration Patterns
- Sharing Stories and Defects between Dev and Test
- Providing Developers with Early Visibility into Requirements
- Associating Planning Items to Requirements
- Associating Planning Items to Implementation Artifacts
- Escalating Help Desk Problems to Developers
- Sharing Customer Feature Requests with Product
- Reporting Known Defects to the Help Desk
- Aligning Testing Teams across Testing Tools
- Populating Requirements into PLM Tools
Demo Videos
Supported Extensions
IBM Engineering Test Management
IBM Engineering Test Management (ETM) (formerly Rational Quality Manager) is accessed via the IBM Engineering Workflow Management application. Therefore, IBM Engineering Test Management will have the same supported features, artifact types, field types, and functional limitations as IBM Engineering Workflow Management.
To access IBM ETM, you will configure a repository connection to IBM Engineering Workflow Management within the Hub application. See the instructions below for more details.
Connector Setup Details
This section describes the basic steps needed to prepare your IBM Engineering Workflow Management instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.
Minimal User Permissions & Hub User
We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.
In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.
Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'
See instructions on how to create a new user in IBM Engineering Workflow Management. Before creating a connection to the IBM Engineering Workflow Management repository, a user with the necessary permissions must be created if one does not exist already. Follow the steps below to create a user with the necessary permissions for use with the connector:
- Access Manage Users.
- Select Create User.
- Fill in details for the user and check JazzUsers under Repository Permissions.
- Select Rational Team Concert – Developer under Client Access License.
- Navigate to the Manage Project Areas and select your project.
- Select Roles and Create Role, filling in the Role Details.
- Now select Permissions, selecting the role you created, make sure the following Permissions are checked under Work Items:
- Under Save Attachment
- Modify attachment
- Under Save Work Item
- Create a work item
- Modify the work item
- Select Overview.
- Under Members, add your user and assign the process role you created above.
Connecting to the IBM Engineering Workflow Management Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format: https://ibmewm.com:9443/ccm
- Best Practice: Log into the project and then look up the connection URL
- Username
- Password
Optional Fields:
- Unassigned User ID (default: Unassigned):
- In EWM, the user ID (and name) of the “Unassigned” user is localized, and is not linked to the Jazz Team Server. This means that if the installation is not in English, the “Unassigned” user could be named something different from "Unassigned" (e.g. “Nicht Zugewiesen” in a German installation). Due to API limitations, a person field (such as assignee) that is set to “unassigned” will have the localized value set. For Hub to know that this localized value (i.e. 'Nicht Zugewiesen') is, in fact, equivalent to 'unassigned,' any non-English installation will need to provide the localized equivalent value for the "Unassigned" user ID in the repository connection settings. By default, the 'Unassigned' user ID is the same as the label appearing in the web UI, but it is possible for an administrator to change the display name. If that happens, paste the following URL into a browser to find the userId HTML element: https://[Url]/service/com.ibm.team.repository.service.internal.IAdminRestService/contributors?searchTerm=[unassigned user name displayed in web UI] Make sure to replace the elements [Url] and [unassigned user name displayed in webUI] with the appropriate values.
- Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: If checked, insecure connections to this repository will be allowed. See details here.
Kerberos/SPNEGO SSO
Planview Hub: 19.3.0.20190625-b79 and later (On Premise only)
Tasktop Sync: 4.19 and later
Required Fields:
- Location/Connection URL
- Example Format: https://SampleServerName:9443/ccm
- Best Practice: Log into the project and then look up the connection URL
- Username
- Login Configuration File
-
The Login configuration file contains the location to the (also required) keytab file. There are two options for where the keytab file may reside (or how to reference it in the login configuration file):
-
Put the keytab file in the working directory of Hub (and reference it just by filename without a path in the login configuration, e.g. keyTab="krb5.keytab")
-
Put the keytab file in an accessible file system location of your choosing and reference it using the file - scheme (e.g. keyTab="file://Users/my.username/Desktop/kerberos/krb5.keytab")
Note: The keytab file contains Kerberos credentials and should be appropriately protected through file permissions (i.e. ensure only Hub service account has access to the file).
-
-
- Kerberos Configuration Information
Additional information can be found here:
- https://www.ibm.com/support/knowledgecenter/en/SSEQTP_9.0.0/com.ibm.websphere.base.doc/ae/tsec_kerb_auth_mech.html
- https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/lab/part6.html#How_to_use_the_new_feature
- https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html
Note: There may be situations (especially with invalid domain/realm information) where a change in the kerberos configuration data will not properly be respected until Hub is restarted. This is due to global internal caching in the underlying JGSS library that cannot be directly influenced.
Optional Fields:
- Unassigned User ID (default: Unassigned):
- In IBM Engineering Workflow Management, the user ID (and name) of the “Unassigned” user is localized, and is not linked to the Jazz Team Server. This means that if the installation is not in English, the “Unassigned” user could be named something different from "Unassigned" (e.g., “Nicht Zugewiesen” in a German installation). Due to API limitations, a person field (such as assignee) that is set to “unassigned” will have the localized value set. For Hub to know that this localized value (i.e., 'Nicht Zugewiesen') is, in fact, equivalent to 'unassigned,' any non-English installation will need to provide the localized equivalent value for the "Unassigned" user ID in the repository connection settings. By default, the 'Unassigned' user ID is the same as the label appearing in the web UI, but it is possible for an administrator to change the display name. If that happens, paste the following URL into a browser to find the userId HTML element:
https://[Url]/service/com.ibm.team.repository.service.internal.IAdminRestService/contributors?searchTerm=[unassigned user name displayed in web UI] Make sure to replace the elements [Url] and [unassigned user name displayed in webUI] with the appropriate values.
- In IBM Engineering Workflow Management, the user ID (and name) of the “Unassigned” user is localized, and is not linked to the Jazz Team Server. This means that if the installation is not in English, the “Unassigned” user could be named something different from "Unassigned" (e.g., “Nicht Zugewiesen” in a German installation). Due to API limitations, a person field (such as assignee) that is set to “unassigned” will have the localized value set. For Hub to know that this localized value (i.e., 'Nicht Zugewiesen') is, in fact, equivalent to 'unassigned,' any non-English installation will need to provide the localized equivalent value for the "Unassigned" user ID in the repository connection settings. By default, the 'Unassigned' user ID is the same as the label appearing in the web UI, but it is possible for an administrator to change the display name. If that happens, paste the following URL into a browser to find the userId HTML element:
SSO Authentication
Additionally, IBM Engineering Workflow Management supports the following SSO implementations:
- Script (HTTP cookies)
- X.509 Certificate
Learn more about how to set up your repository in Planview Hub here.
Creating a Proxy Association Attribute (Tasktop Sync)
A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync.
A proxy association attribute must be created for each artifact type to be synchronized.
The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."
To create a custom string field in IBM EWM. see instructions here.
When using the attribute-based proxy store, a proxy association attribute must be created for each work item type where items are to be synchronized. To create a custom field within an IBM Engineering Workflow Management project:
- Access the Manage Project Area for the given project.
- Navigate to Work Items > Types and Attributes.
- For each Work Item that you would like to sync:
- Select Add... in Attributes and enter your proxy attribute information. Choose either Medium String or Large String forType.
Initialization and Changes Queries (Tasktop Sync)
Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.
The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.
The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.
The IBM Engineering Workflow Management connector has two available types of queries. Project and Type queries search for artifacts based on specified type in the specified project. Query queries search for artifacts of the specified predefined query types.
Query |
Instruction |
---|---|
Initialization Query |
For initializations query, you can choose to use the Project and Type query to retrieve all items of a certain type from one project or choose to use the saved search (query) option and utilize the ability to create queries within EWM. In EWM navigate:
|
Changes Query |
For changes query, you can use the same query as above as the start. To add a "recently modified" filter, create another query that has the same criteria as above. Further, add a "change" filter.
Further, name the query and retrieve it in Tasktop Sync the same way as above. |
Other Configuration Settings
Rich Text
Large HTML
The IBM Engineering Workflow Management Connector supports most extended rich text additions to EWM for Large HTML type fields (i.e. description). To configure, users will need to enable Extended Rich Text presentation on EWM servers of version 6.0.3 and above under "Advanced Properties" of CCM.
Supported in all Hub versions:
- Italics
- Bold
Supported in Planview Hub 18.1+ and Tasktop Sync 4.13+:
- Bullet List
- Numbered List
- Underline
- Strikethrough
- Horizontal Rule
- Text Color
Currently unsupported in Hub due to WikiText style parsing:
- Background Color
- Font Face
- Font Size
- Indentation
Wiki
Planview Hub: 19.1 and later
Tasktop Sync: 4.17 and later
As of version 19.1/4.17, 'Wiki' rich text type is supported.
The following tags are supported by the connector for Wiki Rich Text fields:
- Heading (level 1-6)
- Ordered List
- Paragraph
- Preformatted
- Table
- Unordered List
- Anchor (Link)
- Bold
- Code Span
- Italic
- Underlined
Currently unsupported due to a limitation in WikiText:
- deleted (strikethrough)
Person Reconciliation
For person reconciliation, the following fields are available:
Fields Used for Hub’s Default Person Reconciliation Algorithm |
Field Names for Person Reconciliation Extensions (Note that these are case sensitive) |
Label in IBM EWM |
---|---|---|
ID |
person-id |
User ID (Login Name) |
Username |
person-username |
User ID (Login Name) |
|
person-email |
Email Address |
N/A |
person-display-name |
Display Name |
N/A |
person-item-id |
Item ID (not exposed in web UI) |
N/A |
person-state-id |
State ID (not exposed in web UI) |
person-archived |
Archived (Checkbox) |
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
In general, a full scan is not required to synchronize updates from this repository. However, it is possible that some read-only fields may require a full scan. Please consult with customer care for additional details.
Supported Features
Special Features Supported
You can learn more about special features in Planview Hub here.
Feature |
Custom Type Supported? |
Applicable Hub Versions |
Applicable Repository Versions |
Default Maximum Size in Repository |
---|---|---|---|---|
Time Worked (Worklogs) Impersonation |
N/A |
Tasktop Sync: 4.4 and later |
Any supported repository version: |
N/A |
Comments Impersonation Public/Private |
N/A |
Planview Hub: All Tasktop Sync: 3.5 and later |
Any supported repository version: |
N/A |
Attachments Impersonation |
N/A |
Planview Hub: All Tasktop Sync: 3.5 and later |
Any supported repository version: |
50MB Learn more about maximum attachment size here. |
State Transitions |
N/A |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
N/A |
Supported Artifacts
Supported Work Items
Learn about the difference between containers and work items in Planview Hub here.
Supported Work Item Type |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
---|---|---|---|
Work items:
|
Planview Hub: All Tasktop Sync: 3.5 and later |
Any supported repository version: |
Yes |
Custom work item type |
Planview Hub: All Tasktop Sync: 3.5 and later |
Any supported repository version: |
Yes |
Supported Containers
Learn more about containment in Planview Hub here.
Containers that can synchronize between repositories |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
---|---|---|---|
N/A |
|||
Containers used to define the boundary of a collection (When clicking 'Manage Projects' on a Collection) |
|||
Projects |
Planview Hub: All |
Any supported repository version: |
N/A |
Containers used for artifact routing |
|
|
|
Projects |
Planview Hub: All |
Any supported repository version: |
N/A |
Supported Field Types
Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.
Standard Field Type |
Does Hub support custom fields of this type? |
How is field type referenced in the repository? |
Sample Repository Fields Supported |
Particular Repository Fields NOT Supported |
---|---|---|---|---|
String |
|
Small String Large String |
Formatted ID Id Revision |
|
Single Select |
|
Enumeration Team Area Project Area Process Area |
Filed Against Filed In Priority Resolution Severity Status Type |
|
Multi Select |
|
Enumeration List Team Area List Tags Project Area List Process Area List String list |
Tags |
|
Boolean |
|
Boolean |
Archived |
|
Date |
N/A |
Date |
Creation date |
|
Date Time |
|
Timestamp |
Due Date Modified Date Resolution Date Start Date |
|
Duration |
|
Duration |
Time Spent Estimate Corrected Estimate |
|
Double |
|
Decimal |
|
|
Long |
|
Long Integer |
|
|
Person |
|
User Contributor |
Created by Modified by Owned by Resolved by |
|
Persons |
|
Contributor list Subscriptions (19.2.1/4.18 and later) |
Subscribed by (19.2.1/4.18 and later) |
|
Relationship(s) Learn how to configure relationships in Planview Hub here. |
|
|
|
|
Rich Text |
|
HTML |
Wiki (in 19.1 and later) |
|
Web Links |
OSLC links |
Tracks Tracks Requirement Related Test Case Related Change Request Tracks |
|
Functional Limitations
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Versions |
---|---|---|---|
Third Party API Limitation |
String List Fields Hub does not support listing options for string list fields. |
Planview Hub: All |
Any supported repository version: |
Feature Unsupported |
Custom Link Types Hub does not support custom link types. |
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Configuration Requirement |
Repository Queries When using repository queries, you will need to ensure that the query is sorted by 'Modified Date' in descending order. If you do not do this, Planview Hub will not function properly. |
Planview Hub: All |
Any supported repository version: |
Third Party API Limitation |
Transforms - Summary as Label If your integration contains a transform that includes 'Summary as Label,' the transform will work, however, the summary as label will not be displayed in EWM. |
Planview Hub: All |
Any supported repository version: |
Third Party API Limitation |
Relationship Fields If Hub is synchronizing certain relationship fields between 2 EWM artifacts, the relationship will appear on one artifact (for example, 'contributes to'), but the corresponding relationship will not appear on the other artifact (for example, ‘tracks’), unless ‘tracks’ is also mapped in Hub. This limitation is true for the following relationship pairs:
The limitation does not apply to the following relationship pairs (meaning, the relationships will appear on both artifacts):
|
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Configuration Requirement |
Internal Changeset Link In order to write into the internal changeset link, the target project must have at least one repository workspace associated with it. If no workspace is associated with the project, the connector will not attempt to add or remove changeset links from the target work item. The connector will arbitrarily select one of those repository workspaces when writing a changeset link. |
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Configuration Requirement |
Internal Changeset Link In order to write into the internal changeset link, you will need a custom data transform that will create a proper value. |
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Third Party Functional Limitation |
Creation Date, Created By Fields Starting from EWM 4.0.3, users are not allowed to modify the creation date or created by fields on existing artifacts. Before 4.0.3 this is allowed. In all versions, users may set creation date or created by on newly created artifacts. Any customers with creation date or created by fields mapped will encounter this problem when upgrading EWM to 4.0.3 or higher. The recommended fix is to set the field mapping strategy for EWM for that field to "initialize". |
Planview Hub: All Tasktop Sync: All |
4.0.3 and up |
Third Party Functional Limitation |
Person Fields EWM is case-insensitive and will disallow submission of userIDs that are, ignoring case, not unique on the server, whether the userID is archived or not. |
Planview Hub: All Tasktop Sync: All |
Any supported repository version: |
Third Party API Limitation |
Rich Text EWM encodes the following characters in rich text descriptions: ^ " ~ & are getting encoded to ˆ " ˜ & |
Planview Hub: All Tasktop Sync: All |
5.0+ |
Third Party API Limitation |
Comments EWM encodes the following characters in comments: ^ " ~ & are getting encoded to ˆ " ˜ & |
Planview Hub: All Tasktop Sync: 4.1 and later |
5.2+ |
Configuration Requirement |
Filed Against Value The "Filed Against" pre-condition must be removed if you are flowing work items with no "Filed Against" value. Otherwise a 403 error will result when attempting to create a work item via Hub. By default, "Filed Against" precondition is enabled for all work items. |
Planview Hub: All Tasktop Sync: All |
Any supported repository version: |
Third Party API Limitation |
Authentication Connector is unable to connect to a repository through a non-authenticated proxy. This is due to a bug in the EWM 6.0 client. See: https://jazz.net/library/article/1512 for more info |
Planview Hub: All Tasktop Sync: 4.5 and later |
6.0 |
Third Party API Limitation |
Authentication There is a bug in the EWM 6.0 client that prevents logging in with a non-proxied connection if a user has failed to authenticate against a proxy. There are two workarounds for this:
|
Planview Hub: All Tasktop Sync: 4.5 and later |
6.0 |
Third Party API Limitation |
Custom Multi-Select Fields Any custom multi-select fields of types Process Area list, Project Area list, or Team Area list are read-only due to a third party API limitation. |
Planview Hub: 17.1 - 18.4 Tasktop Sync: 4.9 - 4.16 |
Any supported repository version: |