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.
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.
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.
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"
|"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 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:
sharedspace=Default Shared Space
Note: You can specify clientid and clientsecret instead of username and password
Note: Rally servers may be configured to require an apikey in addition to username/password:
project=Chris Connect Project
Note: versionone servers may be configured to require an access token instead of username/password:
project=Chris Connect Project
Following are parameters that you can append to the command:
Queries and writes out the list of all types supported on a server.
Queries and writes out the list of all fields for the type specified in the property bag.
Directs the extractor to produce a log of the rest queries run in sequence.
Appends the rest http send/receive headers for each executed rest url command in the resturl log.
Produces a separate log of each rest url response in json format.
Directs the engine to append the field/property/column name to each data value in the output
Specific to Rally. Directs the engine to return parent project artifacts in addition to the selected project.
Specific to Rally. Directs the engine to return child project artifacts in addition to the selected project
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.
Splits the output row based on the specified characters. If not specified, the default is |
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.
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.
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:
The following tables describe how the scripts map the data types between pairs of synchronized products:
|Jira data types||QC/ALM data types|
|Jira data types||ALM Octane data types|
|Azure DevOps data types||QC/ALM data types|
When run, the script explores the Micro Focus Connect database as follows:
- Discovers data sources based on the products specified in the script.
- Discovers the connections that use the data sources.
- Discovers the mapped source and target projects in the connections.
- 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.
The Purge utility performs the following actions:
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.
- Deletes all iteration data from the Micro Focus Connect database.
- 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
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"
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.
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.
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.