Batch utility scripts

The following scripts allow you to make your usage of Micro Focus Connect more efficient.

General run notes

Each batch file should be run as Administrator.

The scripts modify the Micro Focus Connect database.

Except for mfcQueryTemplates, each listed script stops the Micro Focus Connect server, runs the appropriate utility, and then restarts the Micro Focus Connect server.

Back to top

ClearWaterMarks

The ClearWaterMarks script resets the watermarks for all active connections.

Resetting watermarks is forces a full synchronization by each connection on the first iteration after the server restarts.

Back to top

DataSourceUsers and UserMaps

The DataSourceUsers and UserMaps utilities can be used together to automate the process of storing mapped user representations from different systems into Micro Focus Connect.

It is useful when the user data is accessible from a common authentication store such as Active Directory or LDAP.

For details, see Automatically create user maps.

Back to top

DataSourceExtracts

The DataSourceExtracts utility extracts a data dump of any type, any subset of fields, for any project across seven products: QC/ALM, ALM Octane, Jira, Azure DevOps, Rally, VersionOne and ServiceNOW.

The command syntax is:

java -jar mfcDataSourceExtracts.jar "almqc" "..\pathTo\almqc.property.bag.txt"

Parameter Details
"almqc" Can be one of the following: almqc, octane, jira, azdo, rally, versionone or servicenow
"..\pathTo\almqc.property.bag.txt" the path to the property bag for the product described by the first parameter.

You can run the script on any machine that has the java jre installed, not just on the Micro Focus Connect server.

The utility receives as input a property bag that describes the connectivity and credentials for the target product.

The parameters in the property bag are a set of key-value pairs in the form of key=value

Key and value guidelines

  • All the keys must be lowercase.
  • Spaces, tabs or special characters are not supported in the key.
  • Do not use quotation marks for the values.
  • Value strings are case sensitive, and must match the corresponding data elements in the targeted product.

Property bag structure per product

Following are structures of each property bag with the minimum required parameters:

Optional parameters

Following are parameters that you can append to the command:

Parameter Description
typemetadata

Queries and writes out the list of all types supported on a server.

Default: false

fieldmetadata

Queries and writes out the list of all fields for the type specified in the property bag.

Default: false

resturls

Directs the extractor to produce a log of the rest queries run in sequence.

Default: false

logrestheaders

Appends the rest http send/receive headers for each executed rest url command in the resturl log.

Default: false

rawdata

Produces a separate log of each rest url response in json format.

Default: false

headers

Directs the engine to append the field/property/column name to each data value in the output

Default: true

attributeids
  • True: Returns the underlying id’s of related fields.
  • False: Returns the names of related fields.

Default: true

scopedup

Specific to Rally. Directs the engine to return parent project artifacts in addition to the selected project.

Default: false

scopeddown

Specific to Rally. Directs the engine to return child project artifacts in addition to the selected project

Default: false

columns

An array of field names. When specified, restricts the output data table to the set of specified fields. If not specified, all the fields of the type are returned. The parameter also directs the engine to optimize the query and fetch all the data in a single round trip.

columns=columnname1,columnname2,columnname3,…

fieldseparator

Splits the output row based on the specified characters. If not specified, the default is |

fieldseparator=^$# splits each field value in a row out separated by the characters specified in the pattern.

Back to top

DeleteConnection

The mfcDeleteConnection utility deletes the connection identified by name in the script.

There is a placeholder variable called ConnectionNameToDelete.

The placeholder must be replaced by a case sensitive exact match of the connection name to be deleted.

Caution: After a connection is deleted, any possible synchronization cross-references associated with this connection will also be deleted.

Back to top

Fix

The Fix script cleans up any corrupt or stale data in the database that is the consequence of an upgrade from earlier versions of Micro Focus Connect.

This script typically will not be used, except immediately after an upgrade.

Back to top

MatchByName scripts

Different products use different models for representing releases and sprints. For example:

  • In Jira, sprints are independent of releases.
  • In ALM Octane, sprints are children of releases.
  • In QC/ALM, release cycles are children of releases, which are contained in release folders.
  • In Azure DevOps, there is no explicit concept of a sprint. The closest are iterations, which are described as tree structures.

The different models make it impractical to synchronize release and sprint entities in one product with their equivalents in the other product.

Instead, we recommend that users manually create releases and sprints (or their equivalents) in the synchronized projects. The release and sprint names in both projects should be identical, including their letter cases.

The MatchByName scripts build tables of matching IDs for the identical releases and sprints in the synchronized projects.

With the tables of matching IDs, Micro Focus Connect can synchronize field values in items, such as stories and defects, that reference releases and sprints.

The following scripts are available for mapping data types between selected pairs of products:

  • matchByNameJiraOctane
  • matchByNameAzureDevOpsAlmQc
  • matchByNameJiraAlmQc

The following tables describe how the scripts map the data types between pairs of synchronized products:

When run, the script explores the Micro Focus Connect database as follows:

  1. Discovers data sources based on the products specified in the script.
  2. Discovers the connections that use the data sources.
  3. Discovers the mapped source and target projects in the connections.
  4. Between the source and target projects, creates tables of matching IDs for identical pairs of releases and sprints (or their equivalents).

You can choose to run the scripts according to the following schedules:

  • Nightly, as part of the Purge script, so that the Micro Focus Connect database can catch up with any newly-added releases or sprints (or their equivalents).
  • On demand by the Micro Focus Connect administrator, based on advice from stakeholders, when new releases or sprints are added to any of the synchronized projects.

Back to top

Purge

The Purge utility performs the following actions:

  1. Generates a de-normalized .txt flat file representation of the audit GUI log entries using the “|” character as the column separator.

    The file is timestamped and written to the Connect/AppData/backup folder. The file can be imported into a spreadsheet or SQL database for backup, querying, reporting or general processing.

  2. Deletes all iteration data from the Micro Focus Connect database.
  3. Purges the dead space from the file system.

You can also produce a subset of the audit columns using the columnnames=columnname1,columnname2,… parameter.

The set of available columns are: itemactionid, iterationid, sourceproject, targetproject, sourcetype, targettype, itemid, associatedid, action, actionvalue, syncguid, fieldname, fieldvalue, starttime, endtime, stacktrace

Example:  

Produce the default report with all column names:

"%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcAudit.jar" "%CONNECT_PATH%" "|" "%BACKUP_PATH%"

Produce a report with a subset of the columns:

"%JRE_PATH%\java.exe" -jar "%UTILITIES_PATH%\mfcAudit.jar" "%CONNECT_PATH%" "|" "%BACKUP_PATH%" "columnnames=starttime,sourceproject,itemid,fieldname,fieldvalue,actionvalue"

Recommended configuration

Set the script to run as a nightly scheduled batch process, preferably at a time that causes the least inconvenience to the user community.

If run every night, this script should require no more than 15 minutes of Micro Focus Connect server downtime.

Stopping and restarting the Micro Focus Connect server clears out the process runtime memory cache.

Back to top

QueryTemplates

The QueryTemplates utility targets the running Micro Focus Connect server.

This script does not stop or restart the server, it does not run direct queries against the Micro Focus Connect database.

This script is a template to query types, properties, and property lists from the data sources.

It is useful when discovering case sensitive property names and/or enum names to set up sync criteria and calculated values.

It is useful for debugging issues with mappings, and is often used by support engineers when working one-on-one with the customer.

Back to top

ResetPassword

The ResetPassword utility Resets the password of the Micro Focus ConnectAdministrator user, replacing it with the string changeme.

This script is especially useful when a customer is locked out of Micro Focus Connect.

A subsequent login through the UI requires changeme to be the specified password, and Micro Focus Connect immediately asks the user to provide a new password.

Back to top