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. The batch mode should always be called with the parameters -application com.yakindu.traceability.batch.application -nosplash --launcher.suppressErrors. Additional command-line options are optional, unless mentioned otherwise below. The following options are supported:

-application com.yakindu.traceability.batch.application Tells YT to run in batch mode and terminate after finished. This option is mandatory.
-data folder Sets the workspace for YT execution to the given absolute file system path. This option is mandatory.
--config /project[/folder…]/file Workspace-relative path to the YT configuration file. This option is mandatory unless loadSnapshot is specified. Can be abbreviated as -conf.
--loadSnapshot file Absolute file system path to a YT snapshot file. When this option is specified instead of the configuration file, No data is fetched, but the snapshot is used for the data extract.
--configParameterFile file Absolute file system path to a properties file with parameter values for the configuration. All parameters and values have to be defined in the configuration.
--configparameter parameter=value Explicitly sets the active value of a parameter in the configuration to a specific value. The value has to be one of the possible parameter values that have been defined for the given parameter.
--timeout seconds How long to wait for the YT core to initialize and adapters to become ready (seconds). 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.
--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!
--import folder[;folder…] Imports additional projects into the workspace. If this option is set, all projects in the workspace directory will be imported. If a folder is given, all projects in this folder and direct children are imported. Multiple folders can be provided by separating them using the system’s filepath separator, which is ; on Windows and : on Linux and macOS. Can be abbreviated as -i.
--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 browse workspace and traceability data to verify whether the correct data is included in the export or not.
--output /project[/folder…]/file Name of the output file relative to the workspace root that was provided by the --data option. Can be abbreviated as -o.
--showDialogs Shows dialogs in the UI thread instead of printing console messages.
--queries queryFile Executes all queries in the query file that is referenced by the path queryFile. It writes the result for each query into a separate CSV file. The CSV file has the same name as the corresponding query, followed by the .csv filename extension. You can use --queries repeatedly to execute queries in more than one file.
--snapshot /project/folder[/folder…] Creates a snapshot in the given folder.
--properties /project[/folder…]/file Path to a properties file containing Java system properties.
--help Lists all available options and their description. Can be abbreviated as -?.

Based on the adapters in use, additional parameters may be required, e.g., to provide credentials to server-based data sources etc.

Please note: It is possible to set Java system properties from a file in order to simplify the usage of the command line. To do so, please use the --properties option to provide the path to the file.

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

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)