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.
A 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 Hub 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).
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:
-
Please review the Git Connector page in our Connector Docs for additional details on configuring the Git repository. This will serve as the source repository in your integration.
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:
Collection Configuration
To configure your source and target collections, please review the instructions below:
-
To configure your source collection (i.e. your Git collection): Outbound Only Collection
-
To configure your target collection (i.e. your Jama or Jira collection): Work Item Collection (Repository)
-
Please also review additional notes 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) |
Model |
Target 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 |
Configuring Relationships for the Target Collection
Note: In order for your integration to run, there must be a mapping in your target collection that tells Hub 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). Hub will default to this transform.
Hub 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, Hub 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, Hub will relate the newly created changeset to all artifact IDs it finds in the commit message.
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.
Select the Code Traceability: Create and Relate a Changeset template.
Note: Depending on the edition of Hub you are using, you may not have all options available.
This will bring you to the New Integration screen.
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).
Artifact Creation Flow
Artifacts will flow in one direction only: from the Git repository to the Work item repository. This cannot be modified.
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.
You will be directed to the 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:
|
Icon |
Meaning |
|---|---|
|
|
A constant value will be sent. Note that:
|
|
|
A state transition will be utilized. Note that:
Note that Hub 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. |
|
|
Collection field is read-only and cannot receive data |
|
|
To create artifacts in your collection, this field must be mapped to your model. |
|
|
This is a required field in your model; it must be mapped to your collection. |
|
|
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. |
|
|
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. |
|
|
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 Hub.
-
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. Hub 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.
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.
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 Filtering, select Artifact Filtering from the right pane of the Integration Configuration screen:
This will lead you to the Artifact Filtering Configuration screen, where you can configure one or more criteria for artifact filtering.
Note: You can click the Collapse All button to view an easier-to-read summary of your artifact filtering statements.
Change Detection
Hub'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.
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)
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.
