Add projects and rules to a connection
The final step in defining a connection is to map the projects in the master and target data sources that will synchronize, and to set up any rules that determine the scope of the data that will be included in the synchronization.
Versions: This topic relates to Micro Focus Connect versions 4.2 and higher.
For the Micro Focus Connect 4.0-4.1 method, see Add synchronization criteria and projects to a connection (4.0-4.1).
The Projects and Rules window contains two main sections: Common projects and data type rules.
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 will synchronize with Workspace 1 in the target data source.
You can define multiple common projects, meaning that the connection will 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:
For details, see Define data type rules.
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 Micro Focus Connect user interface. 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.
Note: Master and Source are not synonymous. Source to Target describes the direction of the synchronization, whereas Master to Target describes the relationship between the product endpoints, with the Master always being Micro Focus. For example, you can set up a synchronization from three ALM Octane workspaces to a single Jira project, (3 masters to 1 target) or from four Jira projects to one ALM Octane workspace (4 targets to 1 master).
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:
- Select only Open defects from Jira Project 1
- Select only In Progress stories from Jira Project 2, and target the same ALM Octane workspace target, using a single connection.
If the above conditions are not met, you must use type specific project maps. This includes:
- 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.
Implementing type specific project mappings
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.
In the following example above, no common projects are listed. A set of type specific project pairs, maps the Jira story to an ALM Octane user story.
In the above example, there are 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.
The 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.
The Type Specific Project Maps mechanism 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 fail with 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:
- Export the connect.xml of the connection. For details, see Export data.
- 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.
- Remove all projects from the Common Projects section.
- Create type specific project maps for each set of projects, for all of the types participating in the connection.
- Add the relevant synchronization criteria to each type set, indicating the choice of artifacts that should synchronize for each synchronization set.
- Change the directions of the synchronizations as required.
- Run the mfcCopyXRefs. Set SourceConnection to the old connection name and TargetConnection to the new one. The script will copy 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.
- Validate the results by performing spot checks on various cross references.
- Delete the old connection and run the new one. For details, see Start and stop connections.
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:
Navigate to the Projects and Rules window in the create or edit connection wizard.
- In the common projects section, click Add Project Mapping.
Select projects from the master and target data sources that you want to synchronize.
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.
- To add additional common projects, click Add Project Mapping.
Project synchronizations are enabled by default. To disable synchronization for common projects, click the Enable/Disable Project Synchronization button.
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 will be 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:
Navigate to the Projects and Rules window in the create or edit connection wizard.
- In the Data type rules section, locate the data type mapping for which you want to define synchronization rules.
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:
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 Build a query.
- Define values that will 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.