Working with customers and in the Jazz.net forum shows there is a strong desire to implement and automate the development processes. Therefore Process customization, especially around work items has always been a major hotspot in RTC adoption. Experience also shows that a lot of the requirements in process customization are driven by process problems and the desire to avoid having to fix the process by customizing the tools instead. This presentation shows the process customization capabilities available in RTC. It also shows examples for requirements that are hard or impossible to implement in RTC and it shows requirements that might indicate that you should consider fixing the process rather than the tool.

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

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

3. Rational Team Concert
Process Customization
Introduction

4. 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
3See the Process Enactment Workshop for an introduction for the first three topics

5. 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

6. 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

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

8. Rational Team Concert
Process Customization
Available Customization Approaches

9. 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

10. 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

11. 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

12. 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

13. 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

14. 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

15. 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

16. 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

17. 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

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

19. 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

20. 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

21. 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

22. 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

23. 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

24. 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

25. 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

26. 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

27. 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

28. 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

29. Thank You
Your Feedback is Important!

30. 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

31. 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