Code Traceability: Create and Relate a Changeset

What is a Code Traceability: Create and Relate a Changeset Integration?

This integration template is only available in editions that have access to the Git repository.  

An integration is quite simply the flow of information between two or more collections.

Code Traceability: Create and Relate a Changeset integration, specifically, creates new work items such as changesets or code commits in a repository such as Jama, when they are sent to Tasktop via an outbound only collection connecting to a repository such as Git.

These types of events are “fire and forget” - they create something new in your repository, but they don’t expect anything back. As such, they don’t mandate a full-blown two way synchronization; a lighter one-way integration can do the trick.  

Here is an example of what you can do with the Code Traceability: Create and Relate a Changeset integration:

  • Flow a Git code commit to a repository such as Jama as a changeset, and relate that changeset to an existing requirement or defect

When you configure your Code Traceability: Create and Relate a Changeset integration, you can customize the field flow, artifact filtering, and change detection for your integration.

Use Case and Business Value

The Code Traceability: Create and Relate a Changeset template allows developers working in Source Control Management tools, such as Git, to flow artifacts, such as code commits, to a Requirements Management tool, such as Jama.

As part of the integration,

  • Changesets, commit messages, or code reviews from an SCM tool, such as Git, will create corresponding changesets in Requirements Management tools, such as Jama
  • Optionally, those newly created changesets can be related to their associated features, defects, or other artifacts in the Requirements Management tool

Template Affordances

The Code Traceability: Create and Relate a Changeset Template allows you to flow artifacts in one direction: from your outbound only collection (i.e. an SCM tool, such as Git) to your work item collection (i.e. your Requirements Management tool).

Template Affordances

Before You Begin

Before you begin configuring your integration, you must configure your repository, model, and collections. Please review instructions below for each step

Repository Configuration

Please review the following pages to learn how to configure your repository:

Model Configuration

You can learn more about configuring your model here: Step 2: Create or Reuse a Model

Below is our recommended ChangeSet model configuration:

ChangeSet Model Configuration

Collection Configuration

To configure your source and target collections, please review the instructions below.

For your target collection,

  • Ensure you are using the same model as your source collection (i.e. the ChangeSet model)

Configure the following mappings: 

Source Repository (Git)ModelTarget Repository (i.e. Jama or Jira)
Short Commit Message (the first line of the commit message)

Short Commit Message

(String or Rich text)

Summary/Name

Commit Message

(the entire commit message)

Commit Message (String or Rich text)

If also mapping Commit Message to description as shown below, ensure transform is set to 'none' for the model on the target collection field mapping

Relationship of choice (i.e. 'relates to')

see details below

Commit Message

(the entire commit message)

Commit Message (String or Rich text)Description


Example Field Mapping for Target Collection

Configuring Relationships for the Target Collection

(warning) In order for your integration to run, there must be a mapping in your target collection that tells Tasktop how to handle relationships between artifacts. This must be done via a relationship-to-string (or relationship-to-rich text) field mapping in the target collection. If no such mapping exists, you will notice an issue on the Activity Screen that will block the integration from running.

To configure relationships for your target collection, go to the Field Mapping screen for that collection, and map the relationship type of choice (i.e., 'relates to') to the Commit Message string field in your model. The transform selected for this field mapping should be String to Relationships (by ID). Tasktop will default to this transform.

Tasktop has built-in smarts to find any artifact IDs present in the commit message, and to then relate the newly created changeset in that target repository to the artifacts identified in that message. For example, if my Git code commit has 'ARTIFACT #123' listed in its commit message, if my relationship is mapped to the 'Commit Message' field in my model, when the corresponding changeset is created in my target repository, it will automatically include a relationship to the existing ARTIFACT #123 in that repository. This will use the String to Relationships (by ID) transformation.

If a relationship field is mapped to the commit message, Tasktop will relate the newly created changeset to the first artifact ID it finds in the commit message (if there are multiple IDs). If a relationships field is mapped to the commit message, Tasktop will relate the newly created changeset to all artifact IDs it finds in the commit message.

Relationship to String Field Configuration

Configuring a Code Traceability: Create and Relate a Changeset Integration

Now that you have all of your base components (i.e., repositories, models, and collections) set up, you can configure an integration to synchronize the artifacts in your collections.

To configure your integration, select Integrations at the top of the screen, then click + New Integration.

Click 'New Integration'

Select the Code Traceability: Create and Relate a Changeset template.

(lightbulb) Depending on the  edition of Tasktop you are utilizing, you may not have all options available.

Select Template

This will bring you to the New Integration screen.

New Integration Screen

Name your integration and select your repositories and collections.

Name Your Integration and Select Your Repositories and Collections

You can click the Overview link on the right side of the New Integration screen to get to the main display screen (shown in the second screenshot).

Click 'Overview'

Overview Screen

Artifact Creation Flow

Artifacts will flow in one direction only: from the Git repository to the Work item repository. This cannot modified. 

Artifact Creation Flow

Field Flow

The field flow configured for a given integration specifies which fields should flow in that integration. For Code Traceability: Create and Relate a Changeset integrations, you can choose to flow a given field (Update Normally) or to not flow a given field (No Update).

To get to the Field Flow screen, click Field Flow on the right pane of the Integration Configuration screen.

Click 'Field Flow'
You will be directed to the Field Flow screen.

Field Flow Screen

You can choose to flow a field ('update normally') or not flow it ('no update'). You'll notice that field flow goes in one direction only — from the outbound only collection into the repository collection.

You can see the names of the mapped artifact fields for each collection on the far left and far right, with the model fields displayed in the middle. By default, model fields without mapped repository fields are hidden. You can see all model fields by checking the ‘Show unmapped fields’ checkbox. Constant values will be identified by a grey box and the constant value icon.

Field Flow Icons

On the Field Flow screen, you will see a number of icons, which will help you understand any special properties or requirements for each field. If you hover your mouse over an icon, you will see a pop-up explaining what the icon means. You can also review their meanings in the legend below:

IconMeaning

Constant Value Icon

A constant value will be sent.

Note that:

  • If the icon is on the side of the collection, this means that a constant value will be sent to your model. This means that any time this collection is integrated with another collection, the other collection will receive this constant value for the field in question.
  • If the icon is on the side of the model, this means a constant value will be sent to your collection. This means that any time this collection is integrated with another collection, that this collection will receive this constant value for the field in question.

State Transition Icon

A state transition will be utilized. Note that:

(lightbulb) Note that Tasktop will update the field flow frequency for fields utilizing state transitions to 'no update.' This is because they are updated via the transition and not via normal 'field flow.' Do not modify the field flow frequency for this field.

Read Only Icon

Collection field is read-only and cannot receive data

Required for Creation Icon

To create artifacts in your collection, this field must be mapped to your model.

Required Icon

This is a required field in your model; it must be mapped to your collection.

Field Not Mapped

This field will not be updated as part of your integration, due to how you have configured it. This field flow configuration can be changed if you'd like.

Prohibited Field Flow

This field will not be updated as part of your integration because the mapping would be invalid. You do not have the option of changing this.

update normally icon

This field will update normally as part of your synchronize integration; this means it will be updated whenever it is modified on the corresponding artifact.

Artifact Routing

Artifact routing is applied based on the artifact IDs included in each commit message. It cannot be configured or modified in Tasktop.  

  • New code commits or changesets will route to the project containing the first related artifact.  For example, if your code commit references ARTIFACT #123, which resides in Project A in Jama, your newly created Jama changeset will be created in Project A as well. If Project A is not a part of your collection, the artifact will either be created in the intended project (if the external repository allows this), or it will be created in the first project in the collection*
  • If your code commit or changeset does not reference an artifact in your target repository, it will be created in the first project listed in the collection*

*Here, by 'first' we mean the first project listed on the Collection Configuration screen. Tasktop will list all projects added at the same time alphabetically. Then once saved, it will add any new projects added under subsequent saves after the initial list of projects.

(lightbulb) Note: For routing to work in a Code Traceability: Create and Relate a Changeset integration with Jama, the commits and their related artifacts must exist in Jama Sets adjacent to each other and must always retain a shared exact parent. Otherwise you will get an error. If the commit does not have a related artifact, they will be created in the root Set of the project in Jama.

First Project Listed in Collection

Artifact Filtering

Artifact Filtering enables you to set filters in order to limit which artifacts are eligible to flow in an integration.

To use a field for artifact filtering, it must:

  • Be a part of your model, and be mapped to the collection you are filtering from
  • Be one of the following field types:
    • Single Select
      • Note that in cases where 'allow unmapped values to flow' is enabled in the model, only fields that are already a part of the model will be considered for artifact filtering
    • Multi-Select
      • Note that in cases where 'allow unmapped values to flow' is enabled in the model, only fields that are already a part of the model will be considered for artifact filtering
    • Date
    • Date/Time
    • Duration
    • String

To configure Artifact Filteringselect Artifact Filtering from the right pane of the Integration Configuration screen:


Click 'Artifact Filtering'
This will lead you to the Artifact Filtering Configuration screen, where you can configure one or more criteria for artifact filtering.  

(lightbulb) You can click the Collapse All button to view an easier-to-read summary of your artifact filtering statements.

Configure Artifact Filtering

Change Detection

Tasktop's default global change detection settings can be found on the General (Settings) screen. However, if you'd like to override the global defaults, you can configure integration-specific change detection and full scan intervals by clicking the Change Detection link.

The Change Detection Interval is the time between polling requests to detect only changed artifacts. This defaults to 1 minute on the General (Settings) screen, but can be customized as desired.

The Full Scan Interval is the time between polling requests to detect changed artifacts, in which all artifacts of a collection are scanned. Not all changes to an artifact will register as a change. Some repositories do not mark items as changed when (for example) a relationship is added or an attachment has changed. These may not be picked up by regular Change Detection, but will be picked up by a Full Scan. This defaults to 24 hours on the General (Settings) screen, but can be customized as desired.  Users can also customize the full scan style for each integration to impact performance and server load, based on their integration and repository configuration.

To configure integration-specific change detection, click the Change Detection link. You can find details on this process here. Note that for a Code Traceability: Create and Relate a Changeset, change detection can only be updated for the source (Git) collection.


Click 'Change Detection'

Viewing Associated Configuration Elements

To view associated configuration elements (such as collections or models that utilize the integration you are viewing), click the Associated Elements tag in the upper right corner of the screen.

View Associated Elements

Associated Elements

Running Your Integration

To run your integration, please see details here: Running Your Integration(s)

Viewing Your Integration

To view your integration, please see details here: Viewing Your Integration(s)