Executing YAKINDU Traceability in batch mode

It is possible to execute YT without requiring any user interactions as a so-called batch command. This allows YT 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 YT in batch mode, it is necessary to provide the appropriate configuration and the workspace as command-line parameters. While running, YT 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 YT’s behavior in batch-mode execution. As YT is based on Eclipse, you can use all Eclipse command line switches . YT also comes with specific switches. The table below lists all YT 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:

Option Description Type
-application com.yakindu.traceability.batch.application Tells YT to run in batch mode. This option is mandatory. Eclipse
-data folder Sets the workspace for YT execution to the given file system path. The path can be relative or absolute. This option is mandatory.

Example: -data workdir specifies the folder <current OS working directory>/workdir as workspace.
Eclipse
-nosplash Avoids application splash screen. This option is strongly recommended. Eclipse
--launcher.suppressErrors If specified, the executable will not display any error or message dialogs. This option is strongly recommended. Eclipse
-config /Project[/folder…]/file Path to the YT configuration file. The path is an absolute path in the Eclipse workspace. This option is mandatory unless --loadSnapshot is specified. The Project containing the file must be imported via --import.

Example: -conf "/Sample.project/conf/demo.conf.yt" loads the file demo.conf.yt from project Sample.project , folder conf .
Can be abbreviated as -conf.
YT
--loadSnapshot file As alternative to activating a given YT configuration which specifies relevant data and their mappings, you can load data from a snapshot which in turn contains a configuration file. The file must hold the absolute file system path to a YT snapshot file.

Example: -loadSnapshot "C:\archive\ytsnapshots\Snapshot_232143.ytsnapshotzip"

The options --loadSnapshot and --config are mutually exclusive.
YT
--configParameterFile file File system path to a properties file with parameter values for the configuration. You can only specify parameters and values which are defined in the YT configuration file (see help section linked above).

Examples:
--configParameterFile ".\myYTParams.txt" loads the parameters from myYTParams.txt which resides in the current working directory.
--configParameterFile "C:\batchjob\conf\myYTParams.txt" loads the parameters from myYTParams.txt which resides in the fully specified path.
YT
--configparameter parameter=value Explicitly sets the active value of a parameter in the configuration. You can specify any number of parameters. A --configparameter has precedence over --configParameterFile. You can only specify parameters and values which are defined in the YT configuration file (see help section linked above).

Examples:
--configparameter variant=A sets the value A for the variant parameter.
--configparameter variant=A --configparameter release=J sets two parameters.
YT
--timeout seconds How long to wait for the YT core to initialize and adapters to become ready (seconds). To say it casually, this is the time to wait for YT loading data. If the timeout expires and YT has not yet finished loading all data, no data will be extracted, except if the --continueNotReady option is given.

Example: --timeout 120 set a waiting time of two minutes.
YT
--continueNotReady This option forces YT to export its data, even if a timeout occurred (see the --timeout option). Use this option with caution, since the exported data most likely is an incomplete representation of your traceability! YT
-import folder[;folder…] Specifies the folder(s) containing the project(s) which are to be loaded into the workspace. If this option is set, all projects in the specified folder(s) and their direct children folders will be imported. Multiple folders can be provided by separating them using the system’s path separator, which is ; on Windows and : on Linux and macOS. Can be abbreviated as -i.

Example: -i „C:/work/platform-projects;./i2/current-project” loads all projects from C:/work/platform-projects and /i2/current-project (relative to working directory).

This option is mandatory if you use the --config or at least one --queries option (as they refer to projects residing in the workspace).
YT
--keepOpen Keeps the application open after the export has been finished. The user needs to close the application explicitly. This option is useful for debugging. After exporting, the user can for instance browse traceability data to verify whether the correct data is included in the export or not. YT
-output file-shortname Name of the file documenting the export statistics (number of exported artifacts and links per type, resp.). As the exported data, the statistics file will be created in the export_gen folder in the batch workspace.
Can be abbreviated as -o.

Example: -data workdir -output stats configures YT to export the statistics into file ./workdir/stats.log .
YT
--showDialogs Shows dialogs (e.g. for warnings or errors) in the UI thread instead of printing console messages. This may be helpful for debugging. YT
--queries /Project[/folder…]/queryfile Executes the queries in the query file that is referenced by the path to queryFile. The path is an absolute path in the Eclipse workspace. Results of queries which are declared as private are not exported. It writes the result for each query both into a CSV file and an Excel file. The CSV file has the same name as the corresponding query, followed by the .csv filename extension, the Excel file gets the .xslx extension. You can use --queries repeatedly to execute queries in more than one file.

Example: --queries P1/queries/demo.queries --queries P2/demo.queries exports the results of file demo.queries (residing in project P1 , folder queries ) and demo.queries (residing in root-folder of project P2 ).
YT
--snapshot /folder[/folder…] Creates a YT-snapshot in the given folder. The folder is resolved in the workspace directory which had been specified by the -data parameter.

Example: -data workdir --snapshot "./export-gen/Snapshot20200909" creates the snapshot in file workdir/export.gen/Snapshot20200909.ytsnapshotzip

The options --snapshot and --loadSnapshot are mutually exclusive.
YT
--properties file System path to a properties file containing Java system properties. You can specify a relative path (relative to working directory) or an absolute file path.

Supported properties by adapters are:
DOORS:
  • DOORS_PATH – Full-qualified path to doors.exe
  • DOORS_USERNAME – username for DOORS-Login
  • DOORS_PASSWORD – password for DOORS-Login


Example:--properties ./yt.props reads system properties from file yt.props in the current working directory.
YT
-eclipse.keyring file Eclipse’s secure store saves data in an encrypted form to provide a single sign-on experience. It helps you to define credentials to log in e.g. to PTC Integrity during remote runs. To achieve this:
  • Log in remote system with YT in UI mode
  • Confirm to store credential in secure store
  • The secure store is a file on your disk. Provide this file during batch runs.

Hint: You can find you current secure store location via the YT Menu Window > Preferences > General > Security > Contents
You can specify a relative path (relative to working directory) or an absolute file path.

Example: -eclipse.keyring C:\users\smith\.eclipse\org.eclipse.equinox.security\secure_storage
Eclipse
-eclipse.password password The master password for Eclipse’s secure store Eclipse
--logFile file Specifies the name of the log file for the batch run. The path is resolved relative to the current working directory. It the file already exists, the log of the new run is appended to the file.

Example: --logFile yt.application.log specifies the log file yt.application.log in the current working directory.
YT
--logLvl level Specifies the log level threshold for the batch run. Possible values are TRACE, DEBUG, INFO, WARN,ERROR, and FATAL.

Example: --logLvl FATAL.
YT
--maxLogFileSize filesize Specifies the maximum log file size. If the log file exceeds this size, it is „rolled”. I.e. the logfile will be renamed from logFile to logFile.1 and for additional log statements a new file logFile is created. The maximum backup index is 1 – YT won’t create a file logFile.2 . That means if one run produces 3 MB of log statements and the maxLogFileSize is set to 1MB , you will lose log data

Example: --maxLogFileSize 4MB
YT
--help Lists all available options and their descriptions.
Can be abbreviated as -?.
YT

Example

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

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

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

Exit codes

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:

Exit code Cause
0 Regular termination
1 Incomplete or invalid parameters from command line
2 An exception occurred, but YT was shut down
3 An error occurred that avoids clean shutdown (like VirtualMachineError or OutOfMemoryError)

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

Generic CSV output schema

With each batch run, YT 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

Batch export CSV schema

  • ArtifactType – Artifact types from the YT configuration
  • LinkType – Link types from the YT configuration
  • LinkableArtifact – All artifacts YT 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 YT, 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 YT configuration (either for artifacts or for links)


p.