What is a Collection?
You can think of a collection as the set of artifacts that are eligible to flow as part of your integration. The process of creating a collection consists of a few steps which whittle down your repository into a smaller subset of artifacts. To create your collection, you will specify:
The repository the artifacts live in
Each collection can only come from one repository
The artifact type (i.e. defect, requirement, test case, etc)
Each collection can only contain one artifact type
The projects within the repository that those artifacts live in
Each collection can contain one or more projects
The model you would like your collection to be mapped to (not pictured)
Each collection can be mapped to one and only one model
You can learn more about collections in the Key Concepts.
Types of Work Item Collections
There are two types of Work Item Collections:
- Work Item (Repository) Collections, which connect to repositories like Jira, Jama, and ServiceNow
- Work Item (Database) Collections, which connect to databases, such as MySQL.
On this page, we will be teaching you how to configure a Work Item (Repository) Collection.
Note: SCM repositories, such as Git, are not available for Work Item collections. To configure an SCM collection, please see Outbound Only Collection instructions.
Check out the video below to learn how to create a new work item (repository) collection:
How to Create a Work Item (Repository) Collection
To create a work item (repository) collection, follow the steps below:
Select 'Collections' at the top of the screen:
Click 'New Collection':
Select "Work Item Collection" as the collection type.
Name and describe your collection.
Select the repository that you would like to connect. The collection will include artifacts from the repository you have selected.
Add projects to your collection by selecting 'Manage Projects'. These are the projects from which Tasktop will be able to create, retrieve, and update artifacts.
Note: In some cases, the word 'Project' is used loosely. You may be selecting workspaces or some other organizational structure, depending on the repository you've connected to. You can review our Connector Docs to see which containers are supported for each repository.
By default, Tasktop retrieves field values from one sample project for mapping. In rare cases where values vary between projects, check the 'Retrieve field values from all projects' box on the Collection configuration screen to retrieve all possible values. Be aware that retrieving values from all projects can take some time.
Select the artifact type from the repository that you would like to include in this collection. Remember, a single collection can only contain artifacts of a single type.
Select the model you'd like to use for this collection.
Note that the projects included in your collection must contain at least one artifact of the type selected. For example, in the image above, there must be at least one bug in Test Project A in Jira in order for your collection to save.
Once you save, you'll see a number of configuration panels appear:
Each configuration panel is an important part of configuring your collection. Make sure you review the links below to ensure you've configured each section appropriately.
Clicking 'Map Fields' will take you to the Field Mapping screen. On this screen, you will be able to specify how fields in your repository are mapped to fields in your model. This mapping will determine how information flows between fields in your source and target collection.
You can learn more about this process on the Field Mapping page.
Map Test Step Fields
Depending on your Tasktop edition, you may see an option to 'Map Test Step Fields.'
You can learn more about this process on the Test Synchronization page.
Clicking 'Configure Relationships' will take you to the Relationship Specification screen. On this screen, you will be able to specify how relationship fields in your repository are mapped to fields in your model. Relationship fields, such as 'blocked by,' 'is related to,' and 'parent,' enable you to preserve the relationship structure between artifacts as you flow information from one collection to the other.
You can learn more about this process on the Relationship Specification page.
Clicking 'Person Reconciliation' will take you to the Person Reconciliation screen. On this screen, you will be able to specify the strategy you'd like to use to reconcile person fields between your repositories.
You can learn more about this process on the Person Reconciliation page.
Clicking 'Configure Comments' will take you to the Comment Configuration screen. On this screen, you will be able to apply a comment extension.
You can learn more about this process on the Comment Configuration page.
Clicking 'Configure State Transitions' will take you to the State Transition screen. On this screen, you will be able to configure state transitions to successfully flow field updates for fields that require defined workflows within your repository.
You can learn more about this process on the State Transitions page.
Optional: Set a Repository Query
If you have enabled repository queries for the repository that you have connected to, you will also see a 'Repository Query' sash at the bottom of the screen:
Note that Repository Queries are advanced functionality, and should only be used when you are truly unable to filter as desired using the built-in Tasktop functionality of Repositories, Collections, and Artifact Filtering.
When configuring your integration, you have several options available to refine which artifacts are eligible to flow.
- First, by defining your repository (for example, Jira)
- Next, when creating your collection, you further refine which artifacts are eligible to flow by selecting only one artifact type (for example, defects), and one or more projects within your repository.
- Next, by configuring artifact filtering at the integration level, you further refine which artifacts can flow, based on fields on those artifacts,
- And finally, by configuring artifact routing, you determine which projects from your collection will participate in the integration, as well as where new artifacts will be created and updated, based on the projects they originated in.
In general, the options outlined above should allow you the flexibility to create collections that are broad enough to be reusable in a range of integrations, while still having fine-grained control at the integration-level to ensure that only desired artifacts are flowing within the context of that integration.
In rare cases, however, you may find that the best option to restrict the artifacts eligible to flow is by setting a query within the repository itself.
If you plan to utilize repository queries, check the box next to 'Enable collections to be refined by setting a repository query,' on the Repository Connection screen.
Once this is selected, you will be able to select a repository query at the Collection level for any collections utilizing this repository.
On the Repository Query screen, you'll be able to search for your desired repository query. Select the query you'd like to use, and click 'Save,' and then 'Done.'
You will then see the selected repository query on the Collection Configuration screen:
Remember, applying a repository query to a collection will only further refine the artifacts included in that collection. If you select a query that encompasses artifacts in projects not in your collection, these artifacts will not be added to the collection unless you also add those projects to your collection as you normally would.
Viewing Associated Configuration Elements
To view associated configuration elements (such as models or integrations that utilize the collection you are viewing), click the 'Associated Elements' tag in the upper right corner of the screen.