Stages RTC-Plugin

Release Notes

v2.3.0 - Extend WorkItems API with save parameters - 24.11.2022

It is now possible to use save parameters in various API functions of the WorkItems API.

// example for saving without sending mails
var saveParameters = ["com.ibm.team.workitem.common.internal.skipMail"]
Api.WorkItems.saveWorkItemWithSaveParams(storyWorkItem, saveParameters );
Api.WorkItems.saveWorkItemAndChangeStateWithSaveParams(childWorkItem, "com.ibm.team.apt.story.defined", saveParameters);

//example for commiting without sending mails
Api.WorkItems.commitWorkItemWithSaveParams(storyWorkItem, saveParameters );
Api.WorkItems.commitWorkItemAndChangeStateWithSaveParams(childWorkItem, "com.ibm.team.apt.story.defined", saveParameters);

v2.2.0 - Java 1.8 and Script Timeout - 30.03.2022

The Stages RTC Plugin is build with Java 1.8.

Timeout Changes

Precondition script timeout is 1min. Follow Up script timeout is 3h. Script Client script timeout is 3h.

v2.1.0 - Stages Dependent Element - 20.01.2022

The Stages RTC Plugin interprets process exports from Stages V7.8 and is able to work with dependent elements.

API Changes

The following functions have been added

Stages Workflow

var enactedElement = Api.StagesWorkflow.getEnactedElement();
var dependent = enactedElement.getDependendElements();

var process = Api.StagesWorkflow.getCurrentProcess();
var dependent = process.getDependendElements();

v2.0.0 - Stages V7 Compatible - 24.02.2021

The Stages RTC Plugin interprets process exports from Stages V7.6 and enables RTC to enhance the functionality of ProjectAreas.

For more information on Stages V7.6 and its new features read the Stages Documentation - Release Notes.

Workflows

The Stages RTC Plugin receives events when a WorkItem is transfered from one state into another. The transfer states could be a specific state, a state group or any state.

Save Workflows in Stages are no longer supported, they could be modeled as Transition Workflows.

Enacted processes from Stages v6 could be automatically transformed into V7 processes. To keep the enactment functionality some adjustments have to be made. Please involve the responsible Product Consultant.

A Guide how to model Stages V7 Workflows is located at Stages Documentation - Model and manage process execution.

Java Script API

The Java Script API allows access to advanced RTC functionality. For a complete description of the functionality see the JavaDoc.

API Changes for V7

The following classes have been removed

• IStagesWorkflow.java
• WorkflowExecutor.java
• WorkflowEngineJob.java
• WorkflowEngine.java
• IWorkflowExecutor.java
• AbstractWorkflowExecutor.java

The following classes have been renamed

• WorkflowProcessElement to WorkflowElement
• WorkflowProcessElementAssociation to WorkflowElementAssociation
• WorkflowState to WorkflowIssueState
• WorkflowWorkproductType to WorkflowIssueType

The following functions have been changed

The new method

public IWorkItem createWorkflowWorkItem(final IProjectAreaHandle projectAreaHandle, final StagesElement stagesElement, @CheckForNull final IWorkItem generatingWorkItem, final String workItemTypeId);

replaces the old method

public IWorkItem createWorkflowWorkItem(final IProjectAreaHandle projectAreaHandle, final StagesElement stagesElement, @CheckForNull final IWorkItem generatingWorkItem) {

so it is possible to specify the type of the generated workItem.

The following methods are deprecated due to the change of the stages model:

@Deprecated
public String getStateAttribute(final StagesElement stagesElement);

@Deprecated
public boolean isGenericWorkItemType(final StagesElement stagesElement);

@Deprecated
public boolean isStateGroup(final StagesElement stagesElement);

Changes in the StagesWorkflowApi.java

- public StagesAssociation getActivityAssociation()
- public StagesElement getAssociatedElement() 
- public StagesElement getCurrentStateElement()
- public String getCurrentStateId()
+ public String getEventEndState()

- public StagesElement getPreviousStateElement()
- public String getPreviousStateId()
+ public String getEventStartState()

- public StagesAssociation getScriptAssociation()
- public String getWorkItemTypeId()
- public StagesElement getWorkProductElement()
- public boolean isAnyCurrentState()
+ public String isEventEndStateAny()

- public boolean isAnyPreviousState()
+ public boolean isEventStartStateAny()

- public boolean isAnyWorkItemType()
- public boolean isCurrentStateGroup()
+ public boolean isEventEndStateGroup()

- public boolean isGenericWorkItemType()
- public boolean isPreviousStateGroup()
+ public boolean isEventStartStateGroup()

- public boolean isSaveWorkflow()
- public boolean isTransitionWorkflow()
+ public StagesElement getActivatorElement()
+ public String getOperationType()
+ public StagesElement getBoundProcessElement()
+ public StagesElement getEnactedElement()
+ public String getScriptParameters()

Migrating Scripts to Stages V7

The following functions have to be replaced:

Enactment 1.0 stages v6	Exection stages v7
StagesWorkflow
.getActivityAssociation()	not supported
.getAssociatedElement()	.getEnactedElement()
.getCurrentStateElement()	not supported
.getCurrentStateId()	.getEventEndState()
.getPreviousStateElement()	not supported
.getPreviousStateId()	.getEventStartState()
.getScriptAssociation()	not supported
.getWorkItemTypeId()	not supported
.getWorkProductElement()	not supported
.isAnyCurrentState()	.isEventEndStateAny()
.isAnyPreviousState()	.isEventStartStateAny()
.isAnyWorkItemType()	not supported
.isCurrentStateGroup()	.isEventEndStateGroup()
.isGenericWorkItemType()	not supported
.isPreviousStateGroup()	.isEventStartStateGroup()
.isSaveWorkflow()	not supported
.isTransitionWorkflow()	not supported

v1.7.0 - Introducing user assignments of stages elements - 24.02.2020

Environment

• RTC 6.0.4 / 6.0.5 / 6.0.6
• Java 8

New functions:

Now, you can access the assigned users from a stages element:

• Use StagesElement.getAssignments() to read the list of assigned users of that Stages element.
• The result is a list of type StagesUserAssignment which has the following new functions:
  • getType(), to read the type of that assigment
  • getUserDisplayName(), to get the display name of the user
  • getUserName(), to get the complete name of the user

v1.6.0 - Introduced 2 additional functions to the Operations API - 01.07.2019

Environment

• RTC 6.0.4 / 6.0.5
• Java 8

New functions:

You can now get the operation data for each supported RTC operations via the operations API:

• getDeliverOperationData
• getSaveClosedChangeSetOperationData
• getSaveParameter

v1.5.0 - Support for Deploy Action - 11.03.2019

Environment

• RTC 6.0.4 / 6.0.5
• Java 8

New Feature - Support for Deploy Action

The new Version of the Stages RTC Plugin can now be triggered, when a ChangeSet is beeing delivered a Stream.

A new API for RTC Scm is part of the new Version:

Including:

• get the names of associated files from a change set
• get the work items associated to a change set

Bugfix

Fixed a bug, which was caused by IDs, stored in work item attributes in old RTC Plugin version. The fix converts the old data into the new format.

v1.5.1 Bugfix

API Function for ChangeSet trigger, recieving WorkItems is now working properly.

v1.4.0 - Delete Links / Test Framework - 08.10.2018

Environment

• RTC 6.0.4 / 6.0.5
• Java 7 / Java 8

New Feature - Stages RTC Plugin Log

The Stages RTC Plugin now allows to delete Links, Supports Java 8 and includes a new test framework.

Deprecated API Version 0 is removed!

v1.4.1 Stages Attribute / createChildrenRelated

Changed stages attributes to be not internal.

Generated review work items now have no more a parent/child relation to the generating work item.

v1.3.0 - Enhanced Logging - 11.08.2017

Environment

• RTC 6.0.3 / RTC 6.0.4
• Java 6 / Java 7

New Feature - Stages RTC Plugin Log

The Stages RTC Plugin now creates its own log file at logs/stages-rtc-plugin.log.

Known Issues

v1.2.3

Rescheduling could theoretically cause loss off link creation. This is caused by RTC Database Exception and only happens on Bulk import >500 WorkItems with complex linking structure. There is no practical problem know. Will be solved with synchronous link creation.

v1.1.1

Stages Workflow Configuration in Eclipse Client is empty. There is no need for configuration via Eclipse.

v1.1.0

Add ChangeSet Trigger is per WorkItem, Remove ChangeSet is per Change Set. Handled by API.

v1.0.0

Not all link Types trigger WorkItem Save Operation. Must be solved by IBM. See: https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=228421

v1.2.0 - ChangeSet-Links / Bulk CSV Import - 11.04.2017

Environment

• RTC 6.0.3
• Java 6 / Java 7

New Feature - ChangeSet-Links

Added API functions for working with ChangeSet-Links

• Receive ChangeSets from WorkItem
• Create Links from WorkItems to ChangeSet

v1.2.1 - Fixed ClassCastException - 20.04.2017

A ClassCastException occurred if an attachment was added to a workItem.

v1.2.2 - Fixed schema/namespace issues - 20.04.2017

Adding the stages plugin to an operation via eclipse client no longer adds the xmlns attribute to the follow-up/precondition entries in the Project Area Configuration XML.

v1.2.3 Bulk CSV Import - 30.05.2017

Database Errors will be rescheduled asynchronous to avoid losing functionality while bulk import.

v1.1.0 - ChangeSet Handling - 28.02.2017

Environment

• RTC 6.0.3
• Java 6 / Java 7

The Stages RTC Plugin receives events when ChangSets are

• added to a WorkItem,
• removed from a WorkItem and
• if a ChangeSet comment is changed.

It enables script handling for ChangSets. The ChangeSets are modelled as Save Workflows in Stages.

v1.1.1 - XML Namespace - 16.03.2017

XML Namespace: Updated namespace definition in export xml.

v1.1.2 - Fixes for NPE, XML and Permission Problems - 07.04.2017

• Added new class to manage REMOVE_LINK events from Modify_Change_Set operations
• Permission problem was solved with the fix above as well
• Added flags to format the injected workflow XML in the project area configuration

v1.0.0 - First stable - 15.08.2016

The Stages RTC Plugin interprets process exports from stages and enables RTC to enhance the functionality of ProjectAreas.

Environment

• RTC 5 / RTC 6.0.3
• Java 6 / Java 7

Save Workflows

The Stages RTC Plugin receives events when a WorkItem is saved. The state of the WorkItem could be a specific state, a state group or any state.

Transition Workflows

The Stages RTC Plugin receives events when a WorkItem is transfered from one state into another. The transfer states could be a specific state, a state group or any state.

Java Script API

The Java Script API allows access to advanced RTC functionality. For a complete description of the functionality see the JavaDoc.

Approvals

The Approvals API provides functionality

• to access approvals and descriptors,
• to create approvals and descriptors and
• it allows to set the approval type and state.

Attachments

The Attachments-API provides functionality to read Attachments from WorkItems.

Attributes

The Attributes-API provides functionality

• to access attributes,
• to change attributes,
• to create custom attributes,
• to get attributes as a specific type and
• to set attributes as a specific type.

Categories

The Categories-API provides functionality

• to receive Categories and TeamAreas and
• to create and to change Categories.

Enumerations

The Enumerations-API provides functionality to receive Enumerations.

Mail

The Mail-API enables sending mails through the rtc standard mail system.

Operation

The Operations-API provides access to

• the WorkItem the operation is performed on,
• all operation parameters and
• the references changed during the operation.

ProjectAreas

The ProjectAreas-API provides functionality

• to create project areas,
• to receive users and administrators,
• to receive and change project areas.

References

The References-API provides functionality

• to create all possible References between WorkItems
• to receive all linked WorkItems,
• and to receive specific WorkItems by LinkType or EndPointDescriptor.

Search

The Search-API provides functionality to set up a individual RTC query based on the WorkItem Attributes.

StagesUtils

The StagesUtils-API provides functionality

• to create specific WorkItems with stages process functionality and
• to add process functionality to WorkItems.

StagesWorkflow

The StagesWorkflow-API provides functionality

• to handle the stages process and
• to receive stages attributes.

System

The Systems-API provides a Logger for the RTC Log.

TeamAreas

The TeamAreas-API provides access to Team Areas.

Timelines

The Timelines-API provides functionality

• to receive Iterations and DevelopmentLines,
• to access Iterations hierarchical and
• to create Iterations and DevelopmentLines.

Workflows

The Workflows-API provides functionality

• to access states and state groups,
• to resolve state resolutions and
• to receive actions for state transitions.

WorkItems

The WorkItems-API provides functionality

• to save WorkItems without running workflow operations,
• to commit WorkItems and run worklflow operations and
• to set specific WorkItem attributes.