Create and manage connections

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

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 to connections:

A connection contains two endpoints, Master and Target. Synchronizations are done between these two endpoints. The Master must be a Micro Focus product, while the target can be any other product, including other Micro Focus 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.

Connection types

Micro Focus Connect allows you to create two types of connections:

MFC Connection. A standard Micro Focus connection with all of the capabilities described in the Micro Focus Connect Help Center. You can create a connection to synchronize between Micro Focus tools such as ALM/QC, and ALM Octane, and third-party endpoints, such as Jira, Azure DevOps, or ServiceNow. For a list of the supported endpoints, see Supported endpoint connectors.
VSM Connection. A Value Stream Management connection with a limited use case of ValueEdge/ALM Octane with Jira. This type of connection allows you to integrate with the Micro Focus ValueEdge technology. For details, see the ValueEdge Integration Hub.

For information on converting a VSM connection to an MFC connection, see Convert connection types.

Define a connection

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

To define a connection:

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

Use the Data Source, Types and Fields, Projects and Rules, and User Configuration tabs to define a connection. Click the Next and Previous buttons to navigate between the tabs. (The VSM connection wizard shows only a subset of 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.
Master Data Source	Select a data source to use as the master data source. You must select a Micro Focus 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 data source.
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.

Click the Next and Previous buttons to navigate between the wizard's tabs: (The VSM connection wizard uses a subset of these 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 Connection scripts.

Manage connections

Use the Modify Connection button to access the actions menu for managing 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 Action 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 Define a connection.
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 ClearWaterMarks.
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 Purge 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.

Clone a connection

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 reflect the new connection.

To clone a connection:

Click the Actions button in the Connect dialog box, 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(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 Connect dialog box, 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 Manage connections.
Edit the new connection as desired. For example, change projects, types, mappings, synchronization criteria, and calculated values.

Move a connection

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.

Next steps: