Work Item Collection (Repository)

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:

1. The repository the artifacts live in

   1. Each collection can only come from one repository

2. The artifact type (i.e., defect, requirement, test case, etc)

   1. Each collection can only contain one artifact type

3. The projects within the repository that those artifacts live in

   1. Each collection can contain one or more projects

4. The model you would like your collection to be mapped to (not pictured)

   1. 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.

Video Tutorial

Check out the video below to learn how to create a new work item (repository) collection:

Creating 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 to. 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 Hub 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, Hub 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.

Note: For instructions on how to include multiple artifact types in a single collection, see the Affinity Modeling section below. 

Select the model you'd like to use for this collection.

Note: 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.  

Click Save.

Tip: Clicking ctrl+s on Windows and cmd+s on macOS will save your collection.

Once you save, you'll see a number of configuration panels appear:

Tip: 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.

Affinity Modeling

Affinity Modeling enables you to model multiple work item types of similar type in a single collection. This means modeling multiple projects and artifact types simultaneously, with fewer collections and field mappings to configure. 

Please be aware of the following limitations before enabling affinity modeling:

• Repositories whose projects depend on type (e.g., Micro Focus PPM) are not eligible 
• Repositories that do not allow project selection (e.g., ServiceNow, BMC Remedy) are not eligible
• Collections configured with a container type are not eligible
• Collections with affinity modeling enabled cannot be used in Container + Work Item Synchronizations

To configure affinity modeling, navigate to the Collection Configuration screen.

On this screen, you’ll see an Options dropdown next to the work item type. 

Select Enable affinity modeling.

A warning message will appear informing you that the artifact types in the collection should use the same artifact schema to prevent synchronization errors. 

After clicking Continue on the warning message, the affinity modeling pop-up will appear.

Here, you can add multiple artifact types to the project(s) in your collection. 

Note: All included artifact types should share the same artifact schema to prevent synchronization errors.

If you need to refresh the fields available for the collection, use the Refresh Fields button in the Hub UI, rather than your browser's refresh button.

If you encounter an error when saving the collection due to a project missing an artifact type, enable Only show projects without type to identify which projects need to be updated.

To save your changes, click Save.

Once configured, you will see all of the types available to be routed on the Artifact Routing screen when configuring your integration. 

Note: Any existing field mappings will be reused for newly added types.

Work Item Treatment for Containers

Enabling Work Item Treatment for Containers gives you the flexibility to synchronize complex integration scenarios with ease and precision. With this feature, you can effortlessly synchronize work item artifacts with container artifacts by treating eligible container artifacts as work items.

Note: As a general rule, any container that can be synchronized between repositories can be treated as a work item. 

To enable this feature, navigate to the Collections screen and click New Collection.

Select Work Item Collection as the collection type.

Note: An existing container collection cannot be converted into a work item collection. A new collection must be created. 

On the New Collection screen, select the repository and add the projects from which you’d like to retrieve artifacts.

After you’ve selected the projects, click Options next to the work item dropdown and select Add container type as work item. 

A pop-up will appear with a warning message informing you that containers cannot be used for artifact routing once they are treated as work items.

After clicking Continue on the warning message, the Manage Artifact Types pop-up will appear where you can select the container you’d like to use as a work item.

Once you’ve chosen the container, click Select.

Select the model you'd like to use for the collection. To save your changes, click Save.