Add projects and rules to a connection

This topic describes the final step in defining a connection—mapping the projects in the Master and Target data sources.

In this topic:

Overview

The final step in defining a connection is to map the projects in the master and target data sources, and add rules that set the scope of the data to be included in the synchronization.

The Projects and Rules wizard page contains two main sections: Common projects and data type rules.

Section	Role
Common projects	Common projects are pairs of projects, from the master and target data sources, that you match together for synchronization. For example, you define that Project A in the master data source should synchronize with Workspace 1 in the target data source. You can define multiple common projects, indicating that the connection should synchronize several pairs of projects in the same two data sources. For details, see Define common projects.
Data type rules	In the data type rules section you can define additional rules for the synchronization of the mapped data types. Each data type mapping is represented in a separate row. For each data type mapping you can define the following rules: Set filters that determine which items are in scope for synchronization. Define conditions and formulas that set field values of synchronized items. Set different project mappings for each data type. By default, all mapped data types are synchronized between the same common projects. Define additional project mappings for a data type set. For each additional project mapping, you can set different synchronization filters and calculated values. For details, see Define data type rules.

Back to top

Common projects vs. type-specific project maps

Common Projects is a mechanism that allows you to group together a set of projects when creating a connection.

You define projects in the Common Projects section in the connection wizard. These projects are used by the type sets that refer to the common projects.

Connection-specific project pairs (sets) can be grouped under Common Projects if the running synchronization is uni-directional or bi-directional, between exactly one source and one target project.

Common Projects allow you to synchronize type-specific data across selected endpoints. However, they do not allow you to apply rules that indicate what can be synchronized. For example, you cannot use Common Projects to apply synchronization criteria such as selecting only open defects from Jira Defects in Project 1 and In Progress Jira Stories in Project 2, with the same ALM Octane workspace target, using a single connection.

Use type-specific project maps for:

• synchronizing multiple sources to target projects.
• running uni-directional or bi-directional synchronizations.
• controlling the set of artifacts harvested from the source or target in either direction.
• applying different synchronization criteria to different types.

The Common Projects mechanism is essentially a subset of type-specific project maps. There is nothing that can be done with Common Projects that cannot also be accomplished with type-specific project maps.

Type-specific project mapping

When using Common Projects with many-to-one project mappings, you cannot set sync criteria or calculated values for a specific source or target project. Instead, use type-specific project maps to ensure accurate mappings. You create type-specific project mappings for each set (source type, target type, source project, or target project).

In this context, you may then apply server filters, sync criteria, and calculated values to each set, making each of them unique. You need to set up a mechanism to distinguish between the artifacts that belong to the individual sync sets. This is necessary when:

• The source endpoint has multiple projects, with workspaces mapped to a single project (or workspace) in the target endpoint.

• The source endpoint has a single project, with a workspace mapped to multiple projects (or workspaces) in the target endpoint.

When using type-specific project maps, you must keep the Common Projects section empty, and describe each master/target project pair in a corresponding Type Rule. If the Common Projects section is not empty, duplications will be triggered across the connection in the following cases:

• you used Common Projects in conjunction with type-specific project maps.

• you did not differentiate between artifacts from the individual syncsets.

Multiple types and projects

The same rules and constraints apply if you synchronize more complex cases such as multiple types from an endpoint to a single type on the other endpoint, or multiple types across multiple projects on one endpoint to a single type/project or workspace on the other endpoint.

When syncing multiple types, you need to create a custom property, typically on the side of the single recipient project/workspace in order to distinguish between the artifacts coming from the other side, the side with the multiple types or projects. This is necessary in order to uniquely distinguish the artifacts when they are created, updated, or written so that they can be guaranteed to always belong to only one type-specific project syncset.

Duplication

Type-specific project maps may not be relevant if you need to synchronize artifacts to multiple projects, in order to duplicate them on the target. This use case is common for sprints or releases, where duplication is required.

A use case where it becomes critical to prevent duplications across projects is when syncing Jira sub-types. If the ALM Octane side artifact is created first, and needs to be synced to a Jira sub-type, it can only synchronization to one project, the project in which its parent type already exists. This step is part of the overall synchronization, but it uses a different synchronization set and cross reference. An attempt to synchronization it to a different project will cause a Jira exception.

Switching from common projects to type-specific user mapping

We recommend using Common Projects when the conditions are met, for example a pure uni-directional synchronization. If at a later time you want to change the connection to bi-directional, follow the steps below.

To adapt a uni-directional connection to a bi-directional connection:

1. Export the connect.xml of the connection. For details, see Export data.
2. Create a new connection by changing the name of the connection in the XML file and re-importing it. For details, see Import, export, and back up data.
3. Remove all projects from the Common Projects section.
4. Create type-specific project maps for each set of projects, for all of the types participating in the connection.
5. Add the relevant synchronization criteria to each type set, indicating the choice of artifacts that should synchronize for each synchronization set.
6. Change the directions of the synchronizations as required.
7. Run the mfcCopyXRefs. Set SourceConnection to the old connection name and TargetConnection to the new one. The script copies the cross references for each implied synchronization set from the common projects connection to the explicit synchronization sets in the type-specific projects of the new connection. For details, see Batch utility scripts.
8. Validate the results by performing spot checks on various cross references.
9. Delete the old connection and run the new one. For details, see Start or stop connections.

Back to top

Examples: Type-specific project mapping

Example 1: Jira Story to ALM Octane Defect

In the following example, a set of type-specific project pairs, maps the Jira story to an ALM Octane user story. No common projects are listed. This example has three type sets:

• ANP:ANP Board to amish
• AP: AP Board to amish
• ANP:ANP Board to amish1

Each type set has its own set of synchronization criteria and calculated values, that can be applied to the master and/or the target.

This example illustrates a bi-directional synchronization that sends some stories from the Jira ANP:ANP Board to amish, and the remainder to amish1. It is also possible to allow the synchronization of all Jira stories from the AP:AP Board to amish. Each of the four types (source, target, source project, and target project) controls exactly what to allow in the synchronization between the two endpoint types/projects, isolating them from other synchronization sets.

The same applies to the ALM Octane side. A user story in ALM Octane with a specific key field value, allows the synchronization criteria in the appropriate master syncset to know the exact the set of artifacts relevant to that syncset. A bi-directional synchronization from ALM Octane to Jira, using the same connection, ensures that the ALM Octane user story does not synchronization to both the ANP and AP projects.

If Common Projects were used in this example, there would only be one type set for the Jira and ALM Octane story types, covering the three sets of common projects. It would not, however, have the ability to control and direct the artifacts being synced.

Example 2: Jira Bugs to ALM Octane Defects

The example below shows the use of type-specific or project-specific syncsets with the use of uniquely distinguishing sync criteria and calculated values. The example maps Bugs in three Jira projects JP-1, JP-2, JP-3 to Defects in a single Octane workspace, OW.

We created a custom field in the ALM Octane workspace, udf_project_key (DisplayName Jira Project Key).

For each of the type-specific project maps, we added a master sync criteria and a matching master calculated value:

Bug-Defect	Project syncset
JP-1 to OW	Master Sync Criteria … Jira Project Key = JP-1 (set the value of Jira Project Key to JP-1) Master Calculated Value Jira Project Key equals JP-1 (only accept defects whose Jira Project Key is JP-1, ignore all others)
JP-3 to OW	Master Sync Criteria … Jira Project Key = JP-2 (set the value of Jira Project Key to JP-2) Master Calculated Value Jira Project Key equals JP-2 (only accept defects whose Jira Project Key is JP-2, ignore all others)
JP-3 to OW	Master Sync Criteria … Jira Project Key = JP-3 (set the value of Jira Project Key to JP-3) Master Calculated Value Jira Project Key equals JP-3 (only accept defects whose Jira Project Key is JP-3, ignore all others)

Back to top

Define common projects

Common projects are the pairs of projects from the master and target data sources that take part in the synchronization.

By default, all the mapped data types are synchronized across the same common projects.

In most scenarios, you will want all the data types to synchronize between the same sets of common projects.

In such a case, define common project mappings in the Common projects section. In the data type sections, leave the default "Default Projects" selection.

To define common projects:

1. Open the Projects and Rules window in the create or edit connection wizard.

2. In the common projects section, click Add Project Mapping.

3. Select projects from the master and target data sources that you want to synchronize.

4. Some SCM tools such as Git and Subversion allow you to specify a deeper directory level synchronization. If available, click the Directory button . Enter the directory path.

5. To add additional common projects, click Add Project Mapping.

6. Project synchronizations are enabled by default. To deactivate synchronization for common projects, click the Enable/Disable Project Synchronization button.

Back to top

Define data type rules

You can define specific synchronization rules for each data type mapping.

If you do not define any rules for a data type mapping, all items in the mapped types are synchronized between the sets of common projects.

You can set data type rules for either the master or target data sources, or both.

To define a data type rule:

1. Open the Projects and Rules window in the create or edit connection wizard.

2. In the Data type rules section, locate the data type mapping for which you want to define synchronization rules.

3. The default rule synchronizes all the type's items between the common projects.

   To add an additional rule for the same data type mapping, click Add Type Rule.

   For each additional rule for a data type mapping, you must select different project mappings.

   To edit a rule, click Edit connection type rule. The Edit Connection Type Rule window opens:

4. Do any of the following:

   • Select the master and target projects to be synchronized for the current data type mapping. By default, the common projects are selected.

     To set a project mapping, click the Change project pair button for the data type rule, or select projects in the Edit Connection Type Rule window.

     Caution: Do not repeat the same project selection in the data sections as in the common projects. Doing so can lead to data duplication and other synchronization errors.

   • Define filters on the data types to limit the synchronization to a subset of items. In the Edit Connection Type Rule window, click a Sync Criteria link for the master or target. For details, see Filter and query data.
   • Define values to be assigned to fields during their synchronization. In the Edit Connection Type Rule window, click a Calculated Value link for the master or target. For details, see Define calculated values.

Back to top

Next steps:

• Filter and query data
• Define calculated values
• Start or stop connections