Change Request Workflow in Jama

By Preston posted 09-21-2015 16:21

This workflow is designed to facilitate the analysis and change of requirements based on a Change Request in Jama. The major goals of this workflow are:
  • Improve visibility into the full impact of a Change Request (CR)
  • Reduce time to review and collaborate on requirement changes with stakeholders
  • Enhance ability to audit and compare versions of requirements 
This workflow is presented as an alternative to the standard CR functionality and is customized beyond Jama's out-of-box CR functionality. (For reference, the standard CR functionality is explained here.) 
1 Preconditions
Your Jama Admin should have the following setup before this workflow can be initiated:
  • Change Request item type with relevant attributes and status values for your organization
  • Relationships widget enabled, Change Request widget disabledThe Change Request widget is a legacy function with some valuable features, but ultimately not as powerful as using Relationships in Jama to link Reqs to CRs.
  • If Relationship Rules are utilized, relevant rules are established to allow links between Change Request item type and impacted items (e.g. Requirements)

2 Create CR and View Impact
When a CR is being considered (prior to approval) the Change Owner will create the CR in Jama. CRs could also be sourced from other systems and synced into Jama via our Jama Integrations Hub or API integration.

Once the CR information is in Jama, the Change Owner will create downstream relationships with individual requirements, specs, etc. that are potentially impacted by the change. This will allow teams to easily see full traceability impact across the project and help assess whether or not to move forward with the CR.

Create Relationships to Impacted Items

  1. Select a Change Request
  2. Navigate to the Relationships Widget
  3. Select button “Relate Items”
  4. Find items to Relate, double-click to add a relationship

View Impact Analysis
Once relationships have been established, the Change Owner runs Impact Analysis reports and determine with colleagues whether or not to move forward on the CR.

Analyze Impact Analysis Report
As there are multiple layers of traceability, any given CR could have a large “ripple effect.” The Change Owner needs to review every item in the impact analysis to determine if they need to change per the CR

  1. If Yes, create a direct relationship in Jama from that item to the CR
  2. If No, move on to the next item

The end result of this analysis effort will be that all impacted items should have a direct relationship to the CR.

3 Create CR Filter and Branch the Impacted Requirements
Create CR Filter
The Change Owner will now create a filter in Jama that shows the CR and all items related to the CR that need to be changed. This will provide a quick reference to these items to quickly baseline and send impacted items for review to stakeholders.

If an existing CR filter already exists, users can simply right-click to duplicate the filter and just change the CR # reference in the filter criteria:

Now Change Owners and stakeholders have a filter to easily see and baseline items related to the CR:

Branching Requirements
Option 1: Baseline
Jama Baselines keep "point in time" snapshots of requirements so if the CR is not approved, all edits and proposed changes can be rolled back. Before any changes are made to the impacted requirements, the Change Owner should create an initial baseline to capture a “before” snapshot of the requirement versions.

Now that all requirements that need to change are related to
the CR and an initial “before” baseline are captured, the Change Owner is ready to update the impacted requirements and review updates with stakeholders. In this approach, changes to the requirements will be visible to all users. It may be helpful to use a workflow status on impacted requirements to indicate they are undergoing changes (e.g. status = Draft rather than Approved)

Option 2: Reuse
This is an alternative option to simply using a baseline. Using Reuse, the Change Owner can actually create a physical branch in Jama. This branch can exist in a separate area of the tree or in an entirely separate Jama project.

This approach requires more manual processing but is beneficial in that the mainline requirements remain unchanged while a separate branch is edited and reviewed. This is helpful if other work such as testing is going on in parallel while the requirement changes are under consideration.

To Reuse, right-click the CR and choose "Reuse."  Make sure you click the option to "Include Related Items and Mirror Relationships" This will ensure you are copying the CR and the related requirements.  You may also choose to create Advanced Reuse rule to handle any special circumstances in your item structure.

Once the Requirements have been branched, you are now ready to update with proposed changes.
4 Update Requirements with Proposed Changes
Change Owners will use the power of Jama’s Review Center and version control to iterate the CR changes and collect feedback. The benefit of using Jama for this process includes:
  • Less Formatting and Rework: versions and comparison views are automatically created by Jama
  • Increased collaboration: Jama provides a single place for all feedback and conversation.
    No more track changes buried in email. Everyone participates on their own time and builds on each other’s feedback.
  • Reduce Meeting time: Resolve major questions or issues before the face-to-face design work sessions

Setup a Review

Find the relevant CR and Send for Review.
For Option 1 - Branch with Baseline you may right-click the CR filter to Send for Review.
For Option 2 - Branch with Reuse, go to the reused branch of requirements. 

To begin, set a deadline, optional settings, and just invite yourself for the first iteration of the review. This will allow Jama to baseline the requirements to be included in the review and give you a chance to see how the Review will appear to your stakeholders. Later, you will publish a new revision of the review with the proposed updates and include stakeholders for feedback.

Once you publish the Review it will appear in Review Center (note – administrator can configure which fields display. By default it is just Name/Description).

Author/Edit the items in the Review

Now that the requirements are contained within a Review, the Change Owner can begin editing the requirements impacted by the CR. They can edit directly in the Project view or Review Center view.

In Review Center, click on an individual requirement to go to the single item view and click Edit:

Publish Review to Stakeholders for Feedback

When the Change Owner has done authoring/editing the requirements it’s time to invite Stakeholders to provide feedback by clicking "Publish Updated Revision"

Change Owners may assign stakeholders either a Reviewer or Approver role:
  • Reviewers: just need to add comments but not officially approve the change.
  • Approvers: add comments and also mark  ‘Approved’ or ‘Needs More Work’

5 Facilitate Stakeholder Review
Stakeholders will receive an email notification to participate in the CR review. When they open the review they see the “proposed” requirement changes but can easily see a side-by-side comparison to the baseline version of the requirement:

Stakeholders may add comments, mark items as reviewed.

The Change Owner may publish several revisions of the Review based on feedback. The review closes when either:

  1. All Reviewers/Approvers approve all items in the review.
  2. The Review deadline is reached.
  3. Alternatively, the Change Owner who initiated the review may close the review manually.

Participants in the review can always refer back to revision 1 of the review to see the original baseline of the requirements:

6 Approve or Reject CR

Based on the Review feedback and analysis on schedule and cost, teams may choose to Approve/Implement the CR or Reject/Close the CR. How you do this depends on which option you chose for branching the requirements: Option 1 - Branch using Baseline:

  • To Approve, the proposed changes are already authored so simply update the CR and Requirement statuses to show the incorporated changes are now Approved
  • To Reject, go to the original Baseline taken for the CR and choose to "Replace Current items with Baseline." This will roll back any proposed change edits in the Requirements. Update CR to appropriate status.

Option 2 - Branch using Reuse:
  • To Approve, right-click the CR branch and choose "view synced items." Select "Compare" and Jama will show differences between implemented requirements and proposed changes per the CR. Synchronize changes from the CR workspace to the mainline.
  • To Reject, update the status of the CR but do no synchronize changes. Leave the CR branch as documentation of the analysis for future reference

7 Create Baseline Comparison Report for Audit History

When stakeholders approve the proposed requirement changes Jama’s Baseline tab will contain the initial baseline prior to changes plus all the iterations of changes during the Review Center collaboration (there may be multiple Review iterations).  The “last” Review baseline represents the final iteration of requirements per stakeholder approval. So comparing the very first Baseline to the very last Baseline shows the before/after view for a specific CR.

The see a before/after view, the Change Owner may create a Baseline Comparison report from Jama. This is a Word report that shows the final side-by-side comparison of existing requirements and changes based on the CR.

#tutorial #administration


02-10-2016 11:26

Preston, thank for the answer. I guess I was looking for a workflow similar to ClearQuest. I guess I would have to stick with the manual feature. 

02-09-2016 22:13

You can assign a change request to a user using the "assigned to" field. If that field is not already on your CR item type, you can add it via Admin > Item Types. (if you're not an admin, just ask your local admin to enable the assigned to field).  

There isn't an "automated" way to lock the item just for that person based on who it's assigned to.  That person could manually lock the CR using actions > lock feature, but that locks the item from editing for everyone including they'd need to manually unlock it, edit it, manually lock it again. When someone locks an item, only that person and admins can unlock it. It sort of gets functionality you desire, but in a manual fashion. 

See more information about locking items here in the help guide.

02-09-2016 16:23


I have a question about assigning a CR to a user utilizing the above described process. Can I assign a CR (during a CCB meeting) a an specific user and somehow lock access to only the user and a administrator?  

I know I can assign CR workflow to groups, I am just curious if I can assign specific CR's to specific users?


09-22-2015 08:02

Good feedback, you're right I've revised my use of the word "Approved" in the intro. I meant for that to be setup as in "this workflow describes is the happy path assuming the CR is approved."  I've added a section that shows how to use the baseline to roll back the proposed changes if the CR is not Approved/Closed.

Branching Requirements w/ Baseline 
In this workflow the branch is essentially the initial baseline I take before any changes are made. Though visually when you view your requirements in Jama it will always show the latest version i.e. the proposed changes to the Reqs, these can be "rolled back" using the baseline.

Some customers like this approach, some customer prefer their requirements to be a more physical branch in a separate Jama workspace. I've added a section on creating a branch using Reuse

Branching Requirements w/ Reuse
This is another benefit of creating a CR with relationships widget as all items can easily be reused from the filter to a different workspace in Jama. There you can make changes, approve via a Review, then synchronize changes back into the main branch.  This requires more processing in Jama, but accomplishes the true physical branch it sounds like you're looking for.

09-22-2015 03:02

This seems like a more robust way than the legacy one, but I'm not sure I like the idea of approving a CR before the changes to derived requirements have been worked out. In my experience you would normally go through the following steps (assuming a non-trivial CR):
  1. File CR
  2. Create a CR branch (i.e. alternate requirement scope) from the current requirement trunk (the current working assumption)
  3. Update all the derived requirements on the CR branch (including things like SW/FW/HW partitioning)
  4. Make a feasibility analysis based on the CR branch (typically the derived requirements will be modified during feasibility iterations between 3 and 4)
  5. Estimate calendar time and resource cost of the implementation changes
  6. Decide if CR should be approved: if so, roll in all the requirement changes related to the CR branch on the development trunk; if not, leave the CR branch as documentation of the analysis for future reference
This revised Jama flow assumes that a decision to approve the CR can be done without formalizing what the derived requirements should be (step 2-4). I think that means providing a weak base for executing step 4 and 5 in the above sequence.

Maybe the pre-change baseline in your flow can be used to revert the trunk back in case the changes are too costly? Still it means all the changes are done on the trunk, rather than on a branch (which is how I believe the legacy functionality is implemented, and seems like a more natural use of the underlying revisioning tool), and processing multiple CRs in parallel could becomes messy.