Create and manage connections

A connection represents the relationship between two data sources. This topic describes how to create and manage your connections.

Overview

A connection represents a synchronization between two data sources (endpoints). Each connection is a collection of a unique pair of synchronization entities, or a syncset. Each syncset consists of a Master Type, Target Type, Master Project, and Target Project pair.

Through the Connection Wizard, you indicate the data sources, types, fields, relationships , and projects to synchronize.

The following guidelines apply:

A connection contains two endpoints, Master and Target. Synchronizations are done between these two endpoints. The Master must be an OpenText product, while the target can be any other product, including other OpenText products. Designating a project as a master or target does not indicate the direction of the data flow, as you can run uni-directional or bi-directional synchronizations.
You can define different synchronization directions at the connection level, artifact type level, or field level.
A pair of mapped types is comprised of a set of mapped fields. Field mappings may be uni-directional or bi-directional. Fields may be strings, numbers, booleans, lists, or references (links).
A connection can include multiple projects. For example, a data source with one project can synchronize to a data source with multiple projects, in both directions.
Connections can contain one or more types paired across endpoints, to include the relationships between objects and their parents. This is useful when synchronizing object hierarchies between products.
Connections can synchronize one-to-one, one-to-many, or many-to-one project type mappings. For example, a one-to-many scenario will synchronize a Jira instance to several ALM workspaces.
By default, any non-string fields are automatically converted to strings. To convert to a specific type (for example, String to Number, String to Reference), use Create and manage connections.
You can limit the scope of items retrieved from the data source for synchronization by defining filters or adding criteria to the data source. For details, see Filter and query data.
When a synchronization runs, it produces a report called an Audit. Audit reports contain records of the items synchronized during an iteration. For details, see Audits.

About connections

You use a connection:

To identify the data source whose assets you plan to synchronize.
To specify the asset types, fields, and relationships you want to synchronize.
To specify the projects you want to synchronize.

You perform these tasks using the Connection Wizard.

The wizard creates an item when it encounters an entity from either data source that it hasn't seen before (based on ID). An item is only created if the default mapping for the type is either bi-directional or in the direction of the item to be created. An item is not created if the data source for the side where the item is to be created has the Allow Create property for the type being created set to false.

When items are created, all of the field mappings are used regardless of the direction of the mapping, to populate the newly created item.

Connection considerations

Caution: To ensure a successful synchronization, the date and time on all endpoint machines or systems must match.

The data sources you want to use for a connection must exist before you can complete a connection. See Create a data source for more information.
You can delete a connection only if there are no project maps or type maps defined for the connection or if you have not run a successful synchronization.
A built-in utility allows you to force-delete specific connections. For details see the DeleteConnection script in Connection management scripts.
Two connections referencing the same source or target endpoint should share the same data source.
A single connection synchronizing data across two projects on the same server endpoint must use different data sources, even though both data sources reference the same endpoint.
The designation of a specific endpoint as master is usually not significant. Several levels within the product are analyzed to detect changes and determine which side made the most recent change. In certain cases where this information is inadequate, the synchronization resorts to the master data source. Most products, however, do provide sufficient details, making the designation of a master insignificant. For data sources that do not merge content, the master designation determines which connector changes are applied when changes are detected in both data sources.

Create a connection

This section describes how to create a connection using the Connection wizard.

To create a connection:

From the Connections tab on the dashboard, click + Connection. The MFC Connection Wizard opens.

Use the Data Source, Types and Fields, Projects and Rules, and User Configuration pages to define a connection. Click the Next and Previous buttons to navigate between the tabs.

Set fields in the Data Source tab:

Field	Description
Connection Name	Enter a name by which to identify the connection. We recommend not using whitespaces in the connection name. If you do need to use whitespaces, enclose the entire name with double quotes. Note: The name cannot be edited after you save the connection.
Master Data Source	Select a data source to use as the master data source. You must select an OpenText product as the master data source. The "master" designation is used as a last resort solution for resolving data conflict. For more details, see Create and manage connections.
Target Data Source	Select a data source to use as the target.
Error Notification	Optionally, use the fields in the Error Notification section to override global error notification email settings specified in Settings. For details, see Troubleshooting.
Sync Settings	In the Synchronization Frequency box, set the interval between synchronizations. Note: Setting a low frequency value creates additional load on the data source product servers. If the data sources are rate limited (typical in cloud instances), you may experience issues or slowdown in synchronization iterations.
Connection Group Settings	Select or create a group for the connection. For details, see Connection groups.

Click the Next and Previous buttons to navigate between the wizard's tabs:

Data Source. See Create a data source.

Types and Fields. See Type mapping.

Projects and Rules. See Add projects and rules to a connection.

User Configuration. See Fallback users.

You can use batch utility scripts to start, stop, and merge connections. For details, see Batch utility scripts.

Managing connections

Use the Modify Connection button to access the actions menu to manage or modify your connections.

To access a connection’s actions menu:

Navigate to the Connections tab and select the connection you want to manage.
Click the gear button Modify Connection, located to the left of the connection name. The actions menu opens.

The following connection menu actions are available:

Action	Description
Edit	Opens the MFC Connection Wizard to the Data Source page. Move between the pages using the Next and Previous buttons. For details, see Create a connection. Tip: Use this option to rename a connection. In the wizard's Data Source page, edit the text in the Connection Name box. (Available from version 24.2)
Clone	Clones the selected connection. For details, see Cloning connections.
Update Labels	Refreshes the field labels for projects in the current connection.
Delete	Removes the current connection. This option is only available to the user who created the connection.
Clear Water Marks	Resets watermarks for the current connection. Watermarks are added to connections to serve as a time and place marker. For details, see Reset watermarks. For details on how to clear watermarks for all active connections using a batch utility, see Batch utility scripts.
Import Cross References	Allows you to select a cross reference file to import into your connection. For details, see Manage cross references.
Export Cross References	Exports the connection's cross reference file in XML format to your Downloads folder. For details, see Manage cross references.
Export Cross Reference Template	Saves a cross reference template file in XML format, to your Downloads folder. For details, see Cross reference file format.
Run One Iteration	Begins running a iteration for the current connection. Track the progress of the run in the Connection tab's Status column, for example, Initializing or Running. After the iteration, a watermark is added to both the source and target with a time stamp. The watermark serves as a time marker, enabling the synchronization to determine what was modified since the last iteration. You can see the watermarks in the Connection Details pane.
Run One Dry Run Iteration	Begins running a Dry Run type iteration for the current connection. A Dry Run iteration runs the synchronization without applying any changes. You can see the planned actions in the audits. Since no actual changes are made, the Status column does not accurately report errors, for example when invalid values are entered. Instead it reports the expected results. This type of run is good for a general test of the connection.
Start/Stop Connection	Starts or stops a connection. For details, see Start or stop connections.
Move Connection	Allows you to move a connection from one server to another. This option is only enabled for multi-node server installations, provided that you have the proper permissions. For details, see Server distribution.
Purge Connection Activity	Deletes all iteration data that is more than one month old, from the database. For details, see Batch utility scripts in Batch utility scripts.
Server Selection	Opens the Server Selection dialog box which allows you to distribute the connections over specific servers. For details, see Server distribution.

Cloning connections

You can clone an existing connection in order to facilitate the creation of a new connection. After you clone a connection, you can edit its details to further customize the connection.

You can perform a cloning through the user interface or by manually editing the connection's XML file.

Clone through the user interface

This section describes how to create a clone of an existing connection and how to edit its details to customize the copy. This is the recommended method for cloning.

To clone a connection from the user interface:

Navigate to the Connections tab and stop all running connections. Note: Failure to stop the connections may cause the database to become corrupted during the cloning.
In the list of connections, select the connection you want to clone. Make sure it is a valid connection.
Click the gear button Modify Connection, located to the left of the connection name. The action menu opens.
Select Clone. A copy of the connection is created. The Connection wizard opens to the Data Source page, with the suffix -Copy added to the name of the original connection. Rename the cloned connection.
Optionally, modify the data source of the new connection. By default, you cannot modify data sources. To enable this option, run the mfcFullRestClient script and set the featureflags.allow_change_datasources_when_copy_connection property to true. For example: java -jar .\mfcFullRestClient-<version>.jar -h <host> -c MyUser,MyPassword -setGlobalPropertyValue -propertyName featureflags.allow_change_datasources_when_copy_connection -propertyValue true. For details, see FullRestClient script for global properties.

Note: You can only change a data source to a data source of the same type. For example, you can change a Jira data source to another Jira data source, but not to an ALM Octane data source.

Caution: If you change a connection's data source, you will often need to make significant modifications to the connection and its endpoint projects. A failure to set up the connections properly, may result in many duplicate items, or the deletion of existing items. It is recommended that you review the changes carefully and that you test the connection in a non-production environment.
Proceed through the wizard using the Next button as if you were creating a new connection. Optionally, change the project for the connection in the Projects and Rules wizard page. For details, see Create a connection.
Perform a complete review of the cloned connection's details, especially if you modified the data source. If the new data source has a significantly different set of projects, types, fields, and users, this could affect the synchronization.

Tip: If you are unable to access the database or connection after the cloning, stop all connections and run mfcMaintenance-24.2.jar -fix. For details, see Maintenance scripts.
Click Save.

Clone manually

This section describes how to create a clone of a connection by manually editing its XML representation.

To manually clone a connection:

Click the Actions button in the dashboard's toolbar, and select Export. The Export Connect Data dialog box opens. For details, see Dashboard toolbar.

Note: The Servers tab is only visible for users with Site roles with a multi-node server installation.
In the Connections tab, select a connection and click Export. A file named Connect(n).xml is saved to your Downloads folder.
Open the Connect(n).xml file for editing.
In the Synchronization section, modify the connection name: <name>New_Connection_Name</name>.
Save the Connect(n).xml file.
Click the Actions button in the dashboard's toolbar, and select Import. The Import Connect Data dialog box opens.
Click Select to locate the Connect(n).xml file. Then click Import. The import begins.

Caution: It is strongly recommended that you stop all running connections before importing cross reference data or a connection.

When the import completes, you have a new connection with all of the type and project mappings cloned from the original connection.
You will be prompted to update items that were not imported such as password. The Import wizard also instructs you to run Update Labels for the imported connection. For details, see Managing connections.
Edit the new connection as desired. For example, change projects, types, mappings, synchronization criteria, and calculated values.

Moving connections

This section describes how to move a running connection from one Connect instance to another.

To move a connection:

Click the Actions button in the top banner, and select Export. The Export Connect Data dialog box opens.

Note: The Servers tab is only visible for users with Site roles with a multi-node server installation.
In the Connections tab, select a connection and click Export. A file named Connect.xml is saved to your Downloads folder.
Open the Connect.xml file for editing.
Optionally, in the Synchronization section, modify the connection name, if you want to use a new name to distinguish between the connections.

<name>Connection name</name>
In the DataSources section, modify the data source names on the new machine, if they are different.

<source>source data source name</source>

<target>target data source</target>
Save the Connect.xml file.
Stop the running connection on the old machine and disable it.
Export the cross references for the old connection. For details, see Manage cross references.
Stop all connections on the target server machine, but keep the Connect server instance running.
Click the Actions button in the Connect dialog box, and select Import. The Import Connect Data dialog box opens.
Click Select to locate the Connect.xml file that you created earlier. Then click Import. The import begins.
Copy the crossreferences.xml file to the target machine, to the usermaps folder.
Edit lines 8 and 9 in the Importxrefs script:

set CROSS_REFERENCE_FILE=NameOfTheCrossReferenceFile.xml

set CONNECTIONNAME=NameOfTheConnection
Save the Importxrefs script and run it is an administrator. Wait for it to complete.
Export the cross references from the new machine. Verify that they match the original cross references. For details, see Manage cross references.
Restart all the connections. Verify that the connection that you created on the target machine is functional.
Delete the old disabled connection from the original source machine.

Next steps: