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:

  • 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.

Back to top

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 connection with all of the capabilities described in the Micro Focus Connect Help Center. You can create a connection to synchronize between OpenText 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.

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

Back to top

Defining connections

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

To define a connection:

  1. From the Connections tab on the dashboard, click + MFC Connection or + VSM 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. (The VSM connection wizard shows only a subset of the tabs.)

  2. 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.
  3. 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 Batch utility scripts.

Back to top

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:

  1. Navigate to the Connections tab and select the connection you want to manage.
  2. 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.

Back to top

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. This method is not available for VSM type connections.

To clone a connection from the user interface:

  1. 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.

  2. Click the gear button Modify Connection, located to the left of the connection name. The action menu opens.
  3. 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.
  4. 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.

    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. In addition, you cannot change an MFC data source to a VSM 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.

  5. 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.
  6. 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.
  7. 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:

  1. 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.

  2. In the Connections tab, select a connection and click Export. A file named Connect(n).xml is saved to your Downloads folder.
  3. Open the Connect(n).xml file for editing.
  4. In the Synchronization section, modify the connection name: <name>New_Connection_Name</name>.
  5. Save the Connect(n).xml file.
  6. Click the Actions button in the dashboard's toolbar, and select Import. The Import Connect Data dialog box opens.

  7. 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.

  8. 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.
  9. Edit the new connection as desired. For example, change projects, types, mappings, synchronization criteria, and calculated values.

Back to top

Moving connections

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

To move a connection:

  1. 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.

  2. In the Connections tab, select a connection and click Export. A file named Connect.xml is saved to your Downloads folder.
  3. Open the Connect.xml file for editing.
  4. 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>

  5. 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>

  6. Save the Connect.xml file.
  7. Stop the running connection on the old machine and disable it.
  8. Export the cross references for the old connection. For details, see Manage cross references.
  9. Stop all connections on the target server machine, but keep the Micro Focus Connect server instance running.
  10. Click the Actions button in the Connect dialog box, and select Import. The Import Connect Data dialog box opens.

  11. Click Select to locate the Connect.xml file that you created earlier. Then click Import. The import begins.

  12. Copy the crossreferences.xml file to the target machine, to the usermaps folder.
  13. Edit lines 8 and 9 in the Importxrefs script:

    set CROSS_REFERENCE_FILE=NameOfTheCrossReferenceFile.xml

    set CONNECTIONNAME=NameOfTheConnection

  14. Save the Importxrefs script and run it is an administrator.
  15. 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.
  16. Restart all the connections. Verify that the connection that you created on the target machine is functional.
  17. Delete the old disabled connection from the original source machine.

Back to top

Grouping connections

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

To choose a connection group:

  1. To change a connection's group, open the connection for editing by clicking on the gear icon and choosing Edit).

  2. In the Connection Wizard's Data Source page, locate the Connection Group Settings section.

  3. Select a Connection Group or click + Add to create a new group. Click Save.

  4. In the dashboard, the Connections tab shows a list of the connections by group. You can expand and hide the contents of each group.

  5. To change the name of a group, click the Edit button adjacent to the group name in the Connection group view.
  6. 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.

Back to top

Convert connection types

Since the VSM connection is only a subset of the MFC connection, you may want to convert it to the MFC connection, since it allows more types and fields. Conversely, you may want to convert an existing MFC connection to a VSM connection, so that you can use it with ValueEdge.

This section describes how to convert an existing VSM connection to a Micro Focus Connect connection. The conversion involves the following steps:

  • Convert the VSM data source

  • Convert the VSM connection

  • Update the cross references

Convert a VSM data source to an MFC data source

This section describes how to convert an existing VSM integration data source to a Micro Focus Connect data source.

  1. In the top banner, click the Actions button and select Export from the menu. The Export Connect Data dialog box opens. Choose the DataSources tab and export the VSM data source. For details, see Import, export, and back up data.

  2. Edit the exported xml file:

    1. Clear the <connectId></connectId> tag for the data source

    2. Change the <contextType>VSM</contextType> to <contextType>MFC</contextType>.

    3. Provide a unique meaningful name within the name tags <name>UniqueName</name>.

    4. Set <VSMMaster>false</VSMMaster> for the data source.

    5. Repeat the above steps for all exported files.

  3. Click the Actions button in the top banner, and select Import from the menu. The Import Connect Data dialog box opens. Import the updated xml file. The new data source is created.
  4. Edit the data source by filling in any additional fields as required, such as the password. There will be missing fields since VSM Integrations require less settings than Micro Focus Connect.

Convert the VSM connection

After you have successfully converted the data source, you modify the connection.

  1. Export these two integrations (data sources) and note the connectId for each, <connectId>xxxyyyzzz</connectId> in the exported xml file. For details, see Import, export, and back up data.

  2. Export the connection. For details, see Managing connections.

  3. Edit the Synchronization section in the exported XML files with the following modifications:

    1. Replace the <sourceDataSourceGuid>xyz</sourceDataSourceGuid> and <targetDataSourceGuid>xyz</targetDataSourceGuid> values for each data source with the connectId values you noted above.

    2. Replace the <source></source>, <target></target>, and <name></name> values with those from the new data source.

    3. Clear the contents of the <connectId></connectId> tag.

    4. Change the <contextType>VSM</contextType> to <contextType>MFC</contextType>

  4. Re-import the connection. After you import a connection, its connection status will be Disabled.

Update the cross references

To complete the conversion, you must update the cross references.

  1. Export the cross references of the original connection. For details, see Manage cross references.

  2. Export the cross reference template for the new connection. For details, see Manage cross references.

  3. Copy the syncset guid from the template file. Replace the guid in the cross reference file with this guid. The guids represent the Project Type criteria that identify a set. Make sure that the types match.

  4. Re-import the modified crossreference.xml file into the new connection.

Tip: Monitor and adapt the data synchronization on an ongoing basis. If the data schema is modified in one of the systems, the configurations might need to be updated, for example, when modifying the available values of the Status/Phase field.

Back to top

Next steps: