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.

Micro Focus Connect creates an item when it encounters an item 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 Micro Focus Connect creates items, it uses all of the field mappings regardless of 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.
Micro Focus Connect provides a helper tool that allows you to force-delete specific connections. For details see the DeleteConnection script in Batch utility scripts.
Two connections referencing the same source or target endpoint can (and 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. Micro Focus Connect analyzes several levels within the products to detect changes and determine which side made the most recent change. In rare cases where this information is inadequate, Micro Focus Connect 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.

Defining connections

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

To define a connection:

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

Use the Data Source, Types and Fields, Projects and Rules, and User Configuration wizard 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 Grouping connections.

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 Update Connection: <Connection name> wizard to the Data Source page. Move between the pages using the Next and Previous buttons. For details, see Defining connections.
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. Micro Focus Connect adds watermarks 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, Micro Focus Connect adds a watermark to both the source and target with a time stamp. The watermark serves as a time marker, enabling Micro Focus Connect 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 a connection.
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 Micro Focus Connect 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 to view 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. Micro Focus Connect creates a copy of the connection. 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 Defining connections.
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.
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 Micro Focus 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 Micro Focus Connect 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 Micro Focus 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.
After the Micro Focus Connect initiates, 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.

Grouping connections

You can group connections into logical groups, for example, by data source. By default, all connections are assigned to the Default Group.

To assign a connection to a group:

To change a connection's group, open the connection for editing by clicking on the gear icon and choosing Edit).
In the Connection Wizard's Data Source page, locate the Connection Group Settings section.
Select a connection group or click + Add to create a new group. Click Save.
In the dashboard, the Connections tab shows a list of the connections by group. You can expand and hide the contents of each group.
To change the name of a group, click the Edit button adjacent to the group name in the Connection group view.
To change a connection's group, open the connection for editing and choose the group name. For details, see Managing connections.

Tip: You can also back up your connection groups through an export, as you would export standalone connections. We recommend that you back up your groups before performing an upgrade, as groups are not preserved when you upgrade your installation. For details, see Import, export, and back up data.

Next steps: