What is an Integration?
An integration is quite simply the flow of information between two or more collections. When you configure your integration, you can customize the field flow, artifact routing, artifact filtering, as well as enable or disable comment flow or attachment flow.
What is a Container + Work Item Synchronization?
The Container + Work Item Synchronization template enables you to flow your folder structure from one repository to the other, along with any corresponding work items (such as defects, requirements, etc) that are contained within that structure. The term "folder" is used loosely, and can refer to many container types, such as folders, modules, or packages.
The Container + Work Item Synchronization template allows you to flow containers and their contained work items between two repositories. The integration will consist of two container collections and two (or more) work item collections from the same repositories.
How to Configure a Container + Work Item Synchronization Integration
Once you have your base repositories and collections set up, you can configure integrations to synchronize the artifacts in those collections.
In this scenario, we'll show you how to configure an integration that flows containers (folders) along with the work items (requirements) contained within them, from a source repository to a target repository.
To configure your integration, select 'Integrations' at the top of the screen, then click '+ New Integration.'
Select the 'Container + Work Item Synchronization' integration template.
Depending on the edition of Tasktop you are utilizing, you may not have all options shown here.
This will bring you to the New Integration Screen:
Name your integration and select your repositories and container collections, and then click 'Save.'
Configuring your Container Integration
Configuring your Container Integration is very similar to configuring a Work Item Synchronization. Please refer to that page for details, while taking note of the key differences outlined below.
Artifact Creation Flow
This process is the same as it is for a Work Item Synchronization. Refer to the Artifact Creation Flow page for details.
Similar to a Work Item Synchronization, you can click 'Field Flow' to configure how fields will flow in your Container Integration. Typically, container integrations will flow significantly fewer fields than a work item integration.
From the Field Flow screen, you can see the names of the mapped repository fields for each collection on the far left and 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 toggling the ‘Show unmapped fields’ checkbox. Constant values will be identified by a grey box and the constant value icon.
You may also notice a warning reminding you to map the parent field in each container collection. Doing so will ensure that nested containers flow to your target collection along with the appropriate hierarchical structure.
Once we map the Parent field in each collection appropriately, you'll see that the warning disappears:
Container Mirroring is similar to the concept of Artifact Routing (within a Work Item Synchronization), but it has some key differences.
On the Container Mirroring screen, you'll see the hierarchical organizational structure contained within each collection. Select the desired top level container on each side. Once joined, Tasktop will know to mirror the container structure underneath in the target collection.
Note that the container structure underneath the top level container will not display in Tasktop unless those container levels can also serve as 'top level containers' for the purposes of mirroring.
Unlike Artifact Routing, Container Mirroring pairs must be one-to-one.
In the example above, any folders contained within the Online Store Requirements project in Jama will create corresponding folders in the Online Store Requirements project in Micro Focus ALM, and vice versa.
Once you've completed mapping your mirrored pairs, you'll see them in the grey sash below:
Container Matching Settings
You'll also notice a Container Matching Settings sash:
Click the 'expand' button in order to configure your Container Matching settings
If you choose to 'match the containers,' Tasktop will proactively find any existing containers that have the same name (summary) across collections (so long as they are in the same level of the mirrored container structure) and match them. When Tasktop 'matches' two containers:
- No new container will be created in the target repository, as a 'matched' container already exists.
- Any work items contained within the matched containers will route to one another, unless the corresponding work item integration's artifact routing overrides that route.
- Any sub-containers beneath the matched containers will mirror one another.
- An event of type, 'associated artifacts,' will be displayed on the Activity screen indicating that the two containers were matched.
You will also be able to specify whether you'd like your matching strategy to be case sensitive or whitespace sensitive, and to specify how Tasktop should handle situations where there are multiple containers in the target hierarchy level that have the same name/summary as the source container.
When configuring a new integration, the container matching settings will default to 'match the containers' with 'error and do not match' selected.
This process is the same as it is for a Work Item Synchronization. Refer to the Artifact Filtering page for details.
This process is the same as it is for a Work Item Synchronization. Refer to the Comment Flow page for details.
This process is the same as it is for a Work Item Synchronization. Refer to the Attachment Flow page for details.
This process is the same as it is for a Work Item Synchronization. Refer to the Conflict Resolution page for details.
This process is the same as it is for a Work Item Synchronization. Refer to the Change Detection page for details.
Configuring your Work Item Integration(s)
To add your Work Item Integration(s), you have two options:
- Creating a new Work Item Integration from this screen
- Importing an existing Work Item Integration
Creating a New Work Item Integration
To create a new Work Item Integration, click '+ New Work Item Integration'
You will be prompted to select the existing work item collections you'd like to add to the integration.
To add a work item collection to the integration, it must:
- be from the same repositories as the container integration above
- include work item types that can take advantage of container mirroring (for example, in the scenario below, we will not be able to add a Micro Focus Defects collection, since only requirements can be routed to Micro Focus requirements folders.)
Once added, click 'Save.'
In general, you will configure this in the exact same way you configure a normal Work Item Synchronization, with just a couple of key differences with regard to Artifact Routing outlined in the Artifact Routing Section, below. Please refer to the Work Item Synchronization page for details on all other aspects of configuration.
Merging an Existing Work Item Integration
If you've already configured a Work Item Synchronization that you'd like to run as part of this integration, you can add it by clicking 'Merge Existing Integrations.'
Note that once you merge your integration, it will cease to exist as an independent integration. You will only be able to access and configure it from this Work Item + Container Mirroring Integration.
To merge an existing integration, it must:
- be from the same repositories as the container integration above
- Note that the order matters – i.e. if the work item integration reverses which repository is on the left vs. right side, an error will occur. For this reason, it is very important to ensure that integrations are created consistently with regard to which repository is on each side.
- include work item types that can take advantage of container mirroring (for example, in the scenario below, we will not be able to add a Micro Focus Defects integration, since only requirements can be routed to Micro Focus requirements folders.)
When merging an existing integration, consider removing any manually configured routes from that imported integration to allow it to take advantage of the automatic routes enabled by the mirrored container structures.
After clicking 'Add Selected,' you'll see that integration added to the Integration Configuration screen.
If you'd like to detach the integration, follow the steps outlined in the 'Detaching a Work Item Integration' section below. Do not click the 'x's in the upper right corner of each collection, as this will remove those collections (along with any associated configuration, such as Artifact Routing) from the integration permanently. Since the merged Work Item Synchronization only exists as part of the Container + Work Item Synchronization, any changes you make to that integration here will be permanent.
Activating the Configuration Pane
To activate the configuration pane for the integration you'd like to modify, highlight the integration by clicking its arrow. This will enable the configuration links for that particular integration.
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.
Detaching a Work Item Integration
If you'd like to detach a Work Item Integration (so that it exists as an independent integration, accessible from the Integrations List page, rather than as part of this Work Item + Container Mirroring Integration), make sure the configuration pane for that integration is enabled (see steps above).
Next, click the 'Detach' button
You will be prompted to name your integration:
You'll notice that the integration is no longer included as part of this Container + Work Item Synchronization:
You'll also notice that you can now access that integration from the Integration List view:
Configuring Your Work Item Integration
In general, configuration for the Work Item Integration contained within your Container + Work Item Synchronization will be very similar to configuration for a typical Work Item Synchronization, with the exception of a few key differences, outlined below. Please refer to the Work Item Synchronization page for details on all other aspects of configuration.
On the Artifact Routing screen for your Work Item Integration, you will see a reference to the existing Container Mirroring configuration that was set up as part of the Container Integration.
Where applicable, your work items will flow in accordance with the Container Mirroring that has been configured. In addition to the routing that is inherited based on Container Mirroring, Artifact Routing can be configured on this page to determine where work items will flow with regard to containers not included in the Container Mirroring structure. If you configure Artifact Routing that contradicts the Container Mirroring configuration, the Artifact Routing configuration will take precedence when determining how work items will flow.
Note: If you would like your artifact routing to match your container mirroring, but to only flow artifacts from a subset of those containers, that use case cannot be accommodated from the Artifact Routing screen here. To satisfy this use case, you will need to detach your work item integration from the Container + Work Item Synchronization. Once detached, you can configure Artifact Routing for the independent work item integration to successfully limit the containers utilized.
Running your Integration
Please be aware that integrations will trigger changes in your end repositories and that misconfiguration can cause items to be duplicated or modified in unexpected ways. Additionally, there is no 'undo' in Tasktop or the repositories. If you have any questions, please contact support.
Since your Container + Work Item Synchronization technically consists of several independent, but interconnected integrations, you can select 'Run All' to run all integrations at once, or choose to run integrations independently.
If for any reason you'd like to run an integration individually, activate that integration's configuration pane by clicking on its arrows, and then click 'Run'
You can also view and run your integration(s) from the Integration List screen. On this screen, your integration will defaulted to the expanded view, where you can run each integration individually:
If you'd like to 'Run All,' you can collapse the view and then click 'Run All':