Executing itemis ANALYZE in batch mode Copy link to clipboard

It is possible to execute ANALYZE without requiring any user interactions as a so-called batch command. This allows ANALYZE to run automatically, e.g., on a continuous integration (CI) server, like Jenkins. This way you can automatically perform certain tasks on a regular basis, e.g., creating reports, documenting the current project state, or archiving it.

When starting ANALYZE in batch mode, it is necessary to provide the appropriate configuration and the workspace as command-line parameters. While running, ANALYZE will load artifacts and links according to the configuration, and it will export its entire knowledge into a generic CSV schema. When that export is finished, the application terminates successfully.

There is a multitude of command-line options available, which you can use to change ANALYZE’s behavior in batch-mode execution. As ANALYZE is based on Eclipse, you can use all Eclipse command line switches . ANALYZE also comes with specific switches. The table below lists all ANALYZE specific switches and important Eclipse switches .

The batch mode should always be called with the parameters -application com.yakindu.traceability.batch.application -data workspace -nosplash --launcher.suppressErrors. Additional command-line options are optional, unless mentioned otherwise below. The following options are supported:

Examples

Here’s an example for a typical ANALYZE batch run call

.\analyze\ANALYZE.exe -application com.yakindu.traceability.batch.application -nosplash --launcher.suppressErrors -data batch_workspace -import „./ANALYZE/workspaces/xsam” -conf „/Sample/input_ea/ea_demo.conf.analyze” -o batchrun.log --queries /Sample/Export.query --queries /Sample/ExportStats.query


It imports all projects from "./ANALYZE/workspaces/xsam" into workspace "batch_workspace" , activates the specified /Sample/input_ea/ea_demo.conf.analyze and exports all raw data and the results of all queries residing in /Sample/Export.query or /Sample/ExportStats.query , resp., into folder batch_workspace/export_gen .

Here is an example for batch run call to generate delta report from the selected configuration


.\analyze\ANALYZE.exe -application com.yakindu.traceability.batch.application -nosplash -data batchworkspace -i „C:\projects\ANALYZE\workspace” -conf „/com.excel.files.test/conf.analyze” --deltaFor „C:\projects\ANALYZE\ANALYZE-Snapshots/test.analyzesnapshot” -console -consoleLog


It imports all projects from "C:\projects\ANALYZE\workspace" into workspace "batch_workspace" , activates the specified configuration /com.excel.files.test/conf.analyze and creates a delta report for the current configuration as snapshot and the snapshot specified in the -deltaFor option into folder batch_workspace/export_gen with the name as DeltaReport.xlsx

Note : Specified configuration /com.excel.files.test/conf.analyze in the above example is relative to workspace selected C:\projects\ANALYZE\workspace

Here is an example for batch run call to generate delta report from the loaded snapshot


.\analyze\ANALYZE.exe -application com.yakindu.traceability.batch.application -nosplash -data batchworkspace -i „C:\projects\ANALYZE\workspace” --loadSnapshot „C:\projects\ANALYZE\ANALYZE-Snapshots\demo.analyzesnapshot” --deltaFor „C:\projects\ANALYZE\ANALYZE-Snapshots\test.analyzesnapshot” -console -consoleLog


It imports all projects from "C:\projects\ANALYZE\workspace" into workspace "batch_workspace" , loads the specified snapshot C:\projects\ANALYZE\ANALYZE-Snapshots\demo.analyzesnapshot and creates a delta report for the current loaded snapshot and the snapshot specified in the -deltaFor option into folder batch_workspace/export_gen with the name as DeltaReport.xlsx

Here is an example for batch run call to generate delta report from the selected configuration


.\analyze\ANALYZE.exe -application com.yakindu.traceability.batch.application -nosplash -data batchworkspace -i „C:\projects\ANALYZE\workspace” --loadSnapshot „C:\projects\ANALYZE\ANALYZE-Snapshots\demo.analyzesnapshot” --uploadProjectID 665 -console -consoleLog


It imports all projects from "C:\projects\ANALYZE\workspace" into workspace "batch_workspace" , loads the specified snapshot C:\projects\ANALYZE\ANALYZE-Snapshots\demo.analyzesnapshot and uploads this snapshot to the Analyze web project with id as 665. This batch run needs username and password of Analyze web user account where project is located.

Here are different ways to assign username and password properties :

• via System properties in batch call : append following properties to the batch command -DANALYZE_WEB_LOGIN_USERNAME=<LOGIN_USERNAME> -DANALYZE_WEB_LOGIN_PASSWORD=<LOGIN_PASSWORD>

Ex :

.\analyze\ANALYZE.exe -application com.yakindu.traceability.batch.application -nosplash -data batchworkspace -i „C:\projects\ANALYZE\workspace” --loadSnapshot „C:\projects\ANALYZE\ANALYZE-Snapshots\demo.analyzesnapshot” --uploadProjectID 665 -console -consoleLog -DANALYZE_WEB_LOGIN_USERNAME=Test_User -DANALYZE_WEB_LOGIN_PASSWORD=passwordText


• via Environment variables :

Kindly set ANALYZE_WEB_LOGIN_USERNAME and ANALYZE_WEB_LOGIN_PASSWORD as environment variables with their appropriate values.

Exit codes Copy link to clipboard

The batch application terminates with exit code 0 when no error was detected. In case of errors, we return other codes depending on the error type, as summarized in the following table:

In case of severe errors reported by the virtual machine which would avoid any handling by ANALYZE, we directly return the corresponding error codes.

Generic CSV output schema Copy link to clipboard

With each batch run, ANALYZE exports all traceability data (artifacts, links, configured artifact types, configured link types) into CSV files. Like query results, the CSV files are created in folder export_gen inside the batch-workspace. The design of the files in intended to support a relational database scheme, so it can be imported easily into any RDBMS.

Batch export CSV schema

• ArtifactType – Artifact types from the ANALYZE configuration
• LinkType – Link types from the ANALYZE configuration
• LinkableArtifact – All artifacts ANALYZE can see, irrespective of whether they are linked or not
• LinkedArtifact – An anchor or link end pointing to a LinkableArtifact. There is no unique constraint regarding this table: Depending on the adapter types that are configured in ANALYZE, there may be multiple representations of the same linkable artifact in this table. On the other hand, there won’t be any representations of LinkableArtifacts that have no links.
• Link – A direct trace link between two artifacts.
• DataSource – The source of an artifact or link. For example, for artifacts from Excel, the DataSource identifier is the filename. For artifacts from Doors, it is the module name.
• Attribute – An attribute that is mapped in the ANALYZE configuration (either for artifacts or for links)

SQL scripts for database import Copy link to clipboard

If a conf.analyzedbmapping file exists beside the configuration file some scripts are generated in the batch run into the „export-gen” folder of the specified workspace.
The file contains mapping information from artifacts or links to tables in the database and artifact or link attributes to columns of the table. Beside the specified columns the tables must have an id column for the foreign key reference to the artifact or link in the LinkableArtifact or Link table and a date column for the current date and time.

The content of the analyzedbmapping file looks like this:

Map from "/Showcase_WiperWasher.Traceability/conf/conf.analyze" to
"jdbc:mysql://localhost/yt-data?serverTimezone=Europe/Berlin&user=yt&password=yt-password" {
	ArtifactMapping "Software Requirements" to table "requirements" {
		"idx" to "RM_ID" 
		"text" to "shortDescription"
	}
	ArtifactMapping "Software architecture" to table "customer_requirement" {
		"id" to "ARCH_ID"
	}
	LinkMapping "TracePointTypeB ⇔ TracePointTypeB" to table "customer_requirement_to_system" {
		"id" to "SYS_ID"
	}
}

It starts with a reference to the corresponding configuration file, followed by the connection string to validate the file and provide content assist. The connection string is not used for the import.

By default these scripts will be generate if one .analyzedbmapping file is found:

1. <configFile>.createANALYZETables.sql: Creation of the default tables for the exported csv file schema.
2. <configFile>.importANALYZEData.sql: Importing the csv files into the generic tables.
3. <configFile>.createANALYZEIndices.sql: Create indices for optimized data access and joins.
4. <configFile>.dbtrafo.sql: transform the imported data based on the specified mapping.

These scripts can be called in the specified order against a mysql connection to import the data.