IBM Engineering Workflow Management

IBM Logo

 

 

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

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.

Creating a New User in IBM RTC

  • 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

Specify Work Item Permissions

  • Select Overview.
  • Under Members, add your user and assign the process role you created above.

Assign Process Role

Connecting to the IBM Engineering Workflow Management Repository

Standard Authentication

Required Fields:

  • Location/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.

Screenshot 2023-10-12 at 10.40.38 AM.png

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
  • 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):

      1. 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")

      2. 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:

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.

Screenshot 2023-10-12 at 11.01.27 AM.png

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)

 
What is Proxy Association Attribute?

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.

Enter Proxy Attribute

           

           

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:

  • Work items → Create Query
  • Define the criteria that you want to follow
  • Name the query
  • When setting up Tasktop Sync, choose the "Query" based search and choose the query that you just saved

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.

Recently Modified 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)

Email

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.

 

 

Frequently Asked Questions

See IBM Engineering Workflow Management connector FAQs here.

 

 

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

1checkicon.png Time Worked (Worklogs)

1Not_allowed.svg.png Impersonation

N/A

Tasktop Sync: 4.4 and later

Any supported repository version:

N/A

1checkicon.png Comments

1checkicon.png Impersonation

1Not_allowed.svg.png Public/Private

N/A

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

N/A

1checkicon.png Attachments

1checkicon.png Impersonation

N/A

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

50MB

Learn more about maximum attachment size here.

1checkicon.png 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:

  • Story

  • Task

  • Defect

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

1checkicon.png String

1checkicon.png

Small String

Large String

Formatted ID

Id

Revision

 

1checkicon.png Single Select

1checkicon.png

Enumeration

Team Area

Project Area

Process Area

Filed Against

Filed In

Priority

Resolution

Severity

Status

Type

 

1checkicon.png Multi Select

1checkicon.png

Enumeration List

Team Area List

Tags

Project Area List

Process Area List

String list

Tags

 

1checkicon.png Boolean

1checkicon.png

Boolean

Archived

 

1checkicon.png Date

N/A

Date

Creation date

 

1checkicon.png Date Time

1checkicon.png

Timestamp

Due Date

Modified Date

Resolution Date

Start Date

 

1checkicon.png Duration

1checkicon.png

Duration

Time Spent

Estimate

Corrected Estimate

 

1checkicon.png Double

1checkicon.png

Decimal

 

 

1checkicon.png Long

1checkicon.png

Long

Integer

 

 

1checkicon.png Person

1checkicon.png

User

Contributor

Created by

Modified by

Owned by

Resolved by

 

1checkicon.png Persons

1checkicon.png

Contributor list

Subscriptions (19.2.1/4.18 and later)

Subscribed by (19.2.1/4.18 and later)

 

1checkicon.png Relationship(s)

Learn how to configure relationships in Planview Hub here.

1checkicon.png

 

 

 

1checkicon.png Rich Text

1checkicon.png

HTML

Wiki (in 19.1 and later)

 

1checkicon.png Web Links

1Not_allowed.svg.png

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:

  • Contributes to / Tracks

  • Affects Plan Item / Affected by Defect

The limitation does not apply to the following relationship pairs (meaning, the relationships will appear on both artifacts):

  • Blocks / Depends on

  • Resolves / Resolved by

  • Duplicated by / Duplicates of

  • Parent / Children

  • Related / Related (pairwise)

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:

  • Authenticate successfully against any proxy, the user can then switch to non-proxied authentication and login

  • Clear the proxy settings in the connection and restart Tasktop Sync. User will then be able to use a non-proxied connection

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: