Rational Team Concert Process Customization What you can and cannot do

Ralph Schoon (ralph.schoon@de.ibm.com)

Unleash the Labs – IBM

rsjazz.wordpress.com

Session Objectives

• Rational Team Concert is used for all kinds of projects, from a couple of users up to thousands of users, to support all kinds of processes

• Every organization has their own challenges and usually wants to modify and enact the process to their needs

• This session intends to show the main methods to customize and enact the process in RTC, best practices and considerations. It also tries to explain what is possible and what is not, based on examples of popular requests asked in the Jazz.net forum or directly by users

• The main points that you should remember at the end of this session are:

– The main methods that are available for RTC customization

– Best practices when considering RTC customization

– Which methods might apply for which customization category

– What you can and what you likely cannot do

1

Rational Team Concert Process Customization Introduction

Ways to Customize the RTC Process

• Basic Process Configuration

– Members, access control, roles, permissions, operational

behavior, timelines, …

• Basic Work Item Process Customization

– Work item types, -attributes, -workflows, -editor presentations,

attribute customization with built-in default values, value sets,…

• Work Item attribute customization using JavaScript

– JavaScript default values, value sets, validators, conditions

• Java Extensions

• Java or REST/OSLC based automation

3 See the Process Enactment Workshop for an introduction for the first three topics

Effort and Complexity – What to Expect

C

O

M

P

L

E

X

I

T

Y

Basic Process

Configuration

Hours/Days

Weeks/Months

Basic Work Item

Customization

Attribute Customization

Using JavaScript

Java Extensions:

Process Behavior

Java Extensions:

Services/Automation/UI

Extension:

Others/Integrations

• Basic Process Customization

– Allows adjusting the basic process rules

• Basic Work Item Process Customization

– Reflects business needs in change management

• Attribute Customization Using JavaScript

– Provides basic custom attribute automation

• Java Extensions

– Client and Server extensions provide flexible options for automation and process enactment

• Java or REST/OSLC based automation

– External tools for administration- and custom automation, reporting, tool integration

4

Common Anti-pattern

• There seems to be a tendency to make the process more and more complex over time

– This is often driven by organizational issues, distrust, desire to control

• Common process creep includes

– Adding more and more work item types

– Adding more and more mandatory work item attributes

• Once added, they are rarely ever questioned or removed

– Creating more complex workflows with many states

• Confusing activities with work item states – mapping of activity diagrams to workflows

– Creating very restrictive processes with a lot of roadblocks

• This can impact performance, cause usability issues, lead to overhead and declining user acceptance

– Process automation like setting attributes is often desired to reduce the overhead introduced

• If a manual process step can be automated, why introduce the step?

5

Best Practice „Keep it simple“ – Stay Lean

• The most successful deployments use an out of the box process and do only minimal customization

– Some few new work item attributes, some out of the box operation behavior

– A good documentation for process and tool mapping and user training

• Best Practices:

– Be restrained when customizing the process

– Question the purpose and value of the customization request

• Are there built-in capabilities that can be used instead?

• Does this set of attributes or the automation really provide benefit?

• How much additional work does this cause compared to the benefit?

• Is the benefit worth the development, test and maintenance of the customization?

– Review the process repeatedly and get rid of complexity no longer required

• New projects or project migration is a good opportunity for simplification

6

Rational Team Concert Process Customization Available Customization Approaches

Basic Process Configuration

Specify

• Members

• Access control

• Timelines

• Roles

• Planning

• Permissions

• Operational behavior

• Work Item customization

Process permissions lookup in Rational Team Concert

Process behavior lookup in Rational Team Concert 8

Basic Work Item Process Customization

• It is possible to

– Define custom work item types and type categories

– Define custom work item workflows

– Define custom attributes

• According to the online help: 100 as maximum for a work item type

• Custom attributes can only be created from a set of built-in types and custom enumerations

– It is not possible to define complex custom attribute data types

• Popular request – Tables: Attribute presentations are limited to the automated placing, it is not possible to place attributes like tables or multiple columns in one section; try to use Wiki type attributes for tables

– It is possible to define a work item type to hold complex information

• Attributes of type work item only show the ID and summary, hover provides more info

• Custom editor presentations could be considered to help

• Keep the numbers low! Less than 10 types, states, a few custom attributes 9

Attribute Customization

• Attribute customization

– Provides default values, calculated values, value sets, validators, conditions

– Is configured for an attribute

• Executes on all work item types with this attribute

– Is implemented by functions

• They always execute when triggered, potentially more than once

• They must return a value

– Is only available in the RTC Eclipse client and the Web UI

• Not available in API based automation or other clients

• Built-in, easy to use attribute customization available

– Simple default values, value sets, validators

• JavaScript can be used to create more flexible attribute customization (above rules still apply)

10

JavaScript Attribute Customization – Limitations

JavaScript seems easy to approach but

• The RTC JavaScript API is very limited

– Only supports a limited subset of “simple” attribute types (text, number types, enumerations)

• Can currently not create working HTML tags in String/HTML based attributes

– Can not modify more than one work item attribute (as it is a function)

– Can only read attributes of the work item in which context the scripts runs

• Can not access data outside of the work items context; can not access or modify complex data such as comments, attachments, approvals, links, linked items, get or set values on other items

• For attributes representing complex items such as users, timelines, iterations

– Only the UUID and the label/display name are available, no access to additional information

• E.g. no access to user roles, no access to the team area- or timeline hierarchy

– To set values for these types script must return the item UUID

11

Attribute Customization Summary

• The built-in attribute customization provides only the most basic needs • Simple default values and basic value sets that provide choices and limit combinations

• JavaScript attribute customization provides a bit more capabilities

– Pro: It does not require any deployment support

– It appears to users initially as a simple approach

• But it is very limited in what it can do

• It is only available in Eclipse and the Web UI

– Users are often unaware of and struggle with these limitations

• More complex process enactment needs to be implemented using the Java API

12

RTC Java API and Java Extensions

• RTC provides Java API’s in a Client and Server SDK

• RTC can be extended using Java extensions

– Extensions are Eclipse plug-ins implementing the

interfaces defined by existing extension points

• Execution context is the server or an Eclipse client

• Extensions must be deployed in their extension context

• Developing extensions is not trivial and requires

experience (Java, Eclipse plug-in development)

– The RTC Extensions Workshop provides an introduction

– The blog rsjazz.wordpress.com provides additional

guidance, examples with downloadable code and explains

how the API in several areas works 13

Common Java RTC Extensions

• Java Work Item Customization Provider

– Java instead of JavaScript provides a lot more API access

• Access to project/team areas, members, roles, timelines, attachments, comments, work item links and linked work items

– Example: Java Based Value Providers, Conditions and Validators

• Pre-conditions/advisors

– Provide process rules and rule enforcement, can prevent operations

– Work on specific Operation ID’s such as work item save or deliver

– Have access to the full API of their extension context (client/server)

– Example: Only Owner Can Close Work Item Advisor

• Follow up actions/participants

– Used for post processing, run a build, send e-mail, modify data

– Implemented similar to pre-conditions, can also prevent/roll back operations if they fail e.g. if no build could be started

– Example: Resolve Parent If All Children Are Resolved Participant

14

Common Java RTC Extensions Cont…

• Asynchronous tasks

– A server task that runs periodically and performs operations

– Example: Due Date Notifier

• Custom Editor Presentations

– Special editor presentations to display and modify attributes

– Example: Jazz Wiki on Contributing Attribute Presentations

• Editor Actions and Menu Extensions

– Examples: Eclipse Context Menu Extension; Web UI action

• Custom Dashboard Widgets

– Example: Timebox Planning View – RTC widget allows iteration planning in a “Tetris-Like” way

• Event handler

– Called for events, can perform event based tasks based e.g. send mails on state change

15

Automation / Integration

• RTC provides Java or REST/OSLC based API’s

for automation and integration

– Administration tools

• User management, project area management

– Automation for builds

• Publishing, deployment

– Collecting data for monitoring/reporting

– Creating tool integrations

• Synchronizer, Connectors, OSLC Consumers, Providers

16

Rational Team Concert Process Customization Examples, what you can and what you cannot do

Trending Questions – Custom E-Mail Notification

• Custom E-mail notification: very popular request; often hidden behind

– Automatically set ownership to a work item

– Automatically subscribe a user, team or group of users to a work item

• Consider available capabilities implemented to reduce mail traffic

– Dashboards to show work item queries and -results

– RSS feeds showing team activities

• Custom mail notification is possible using various options like

– Custom follow up actions that trigger at work item save

• Subscribe users, automatically set owners or send e-mails based on complex criteria

– Custom scheduled asynchronous tasks, see Due Date Notifier

– Custom event handlers

18

Trending Questions – Work Item Data Calculation

• The request to calculate data across one or more work items is popular;

the following approaches can be used:

– It is possible to use work item save follow up actions

• Triggers on save and can detect changes that drive the calculation

• Example: RTC Update Parent Duration Estimation and Effort Participant

– Attribute customization using JavaScript/Java can be applicable

• Trending question: reporting how often a work item was in a state

– Use Jazz Reporting Service 6.0.1

– Use a follow up action detecting the state change and a count attribute

• Attribute customization could be used but it is hard to detect a state change

– Calculate based on work item history in a batch client?

19

Trending Questions – Read Only, Required Attributes

• Attributes can be set

– Read only in the attribute definition or editor presentation

– Read only or required using built-in pre-conditions

• Based on work item type and state

• Based on JavaScript or Java Attribute Customization conditions

• The methods above provide hints in the UI to indicate that the attribute is required or read only

• It is also possible to create custom pre-conditions

– Such a solution can not show indicators in the UI

• The user will only see the advisor error on save similar to missing permissions to modify attributes

20

Trending Questions – Hiding Work Item Attributes

• RTC allows built-in attribute presentation hiding in the work item editor for some cases e.g. on work item creation, in work item states

– An editor tab can be hidden if all contained attribute presentations are hidden

• Hiding presentations in the work item editor does not hide the data in queries, plans, reports, or other places

• It is not possible to customize work item attribute hiding

– No capability to hide on custom conditions

– No extension point for custom logic

• Several enhancement requests in this area; see ER 260952

– A real solution is likely very complex and impacts performance 21

Trending Questions – Restricting Access to Data

• It is possible to restrict read access to work items and SCM elements*

– Restrict access based on access groups, project or team areas

• Work Items: manual selection or automation based on the category

• SCM elements: manual selection

• Custom automation to set access control is possible

– Asynchronous tasks, event handlers or external automation

– Follow up actions can be used in some scenarios

• Since hiding individual work item attributes is not possible, use a related work item with limited read access to store confidential data

*Partially available for SCM since 5.0.2, complete since 6.0.1 22

Trending Questions – Dynamic Workflow

• Does RTC support dynamic workflows?

– No, the workflow for RTC work items is fixed

• Pre-conditions/advisors can be used to prevent state changes that are not desirable; the

action can still be selected

• Use a follow up action to set the work item state

• Does RTC support dynamic creation of attributes?

– RTC does not support dynamic creation of attributes

• There are limits on how many attributes a RTC work item type can have

• It is not possible to delete attributes in RTC

• It is possible to create attributes programmatically but they must be entered into the

process XML to be able to see them in the UI

23

Trending Questions – Extending Planning

• There are many questions around extending the planning components

– This includes accessing plan data such as rank, schedule and progress

• There is no public planning API

– This prevents accessing data in plans

– The planning component stores some internal data in work items, but access through work items does not allow to get the data as displayed in the plans

• There is API available to modify other data that influences planning

– Estimation and complexity attributes in work items

– Filed against and planned for attributes in work items

– User allocation, scheduled absences information can be manipulated

24

Trending Questions – Customizing User Records

• This has come up multiple times e.g. to

– Be able to provide a contact information or a phone number

– Be able to provide a company name or address

• It is currently not possible to extend the user record and the UI to show additional data

• It would be possible to use a work item type to represent more user data

– It might be possible to show the data for the user in the UI

• Using a custom editor presentation

• Using a follow up action that generates the data in a text attribute

25

* mockup

SCM and Other Domains

• Other requests for special process customization

related to the SCM system i.e. gated delivery

– It is possible to create and use pre-conditions to

check rules and follow up actions to add automation

to various SCM operations

– It is not possible to prevent or act on check ins, see Enhancement 375669

• There is no check-in operation available to be used in extensions

• Various other domains like Build and Process support pre-conditions

and follow up actions

– Very few activity on Jazz.net in extending these domains

• More desire for automation in these domains

26

Summary

• Rational Team Concert provides means to customize the

change and configuration management process

– Customization requires a good understanding how RTC works

• The complexity ranges from simple configuration to

complex extensions, integrations and automation

– Most non trivial customization requires Java Extensions

– There are limits for what can be achieved

• It is important to keep in mind that not all that can be done

is necessarily beneficial – keep it simple

27

Thank You Your Feedback is Important!

Process Configuration and Customization

• Process Enactment Workshop for the Rational solution for Collaborative Lifecycle Management

• Customization of Work Items in Rational Team Concert

• Changing your Rational Team Concert Process Configuration – Best Practices

• Work Item Configuration and Shared Process in Rational Team Concert

• Process permissions lookup in Rational Team Concert

• Process behavior lookup in Rational Team Concert

• Attribute customization Developer Wiki

• Attribute Customization Overview – Attribute Types and size limits

• Accessing Enumeration List attributes in JavaScript

• JavaScript Debugging with Chrome

• Debugging JavaScript

29

Process Configuration and Customization Links

• Rational Team Concert Extensions Workshop

• Learning To Fly: Getting Started with the RTC Java API’s

• Interesting Links around Customizing RTC

• Open Services for Lifecycle Collaboration Workshop

• Community Examples

– https://rsjazz.wordpress.com/ provides many examples

– Extension to generate unique custom work item numbers

– JAM – Jazz Workallocation Manager A lightweight Web client to manage the Workallocation of users or team within Jazz/RTC

– Timebox Planning View – A new widget for RTC to allow iteration planning of work items in a “Tetris-Like” way

– Code to disable e-mail notification for the users during mass work item updates

– Project Area Creator

30