Project Build Parameters

The easiest way to obtain the command line parameters for creating a project is to retrieve it from Squore Server GUI.

From the GUI, create a new project and set up the parameters as needed, then at the bottom of the last page of the project creation Wizard, Confirmation, have a look at the "Squore agent command line" section:

CLI first project parameters
Figure 1. Project parameters for command line use

From there, copy the project build parameters on the right side of the "--" separator and append them to the Squore Agent command line:

java -jar /path/to/squore-agent.jar -u demo -- --commands="DELEGATE_CREATION" --name="myFirstCommandLineProject" --version="V1" --wizardId="ANALYTICS" --dp="type=SQuORE" ...

The list of available parameters can be found in the following sections, categorized by common purpose.

Commands

-c "COMMAND", --commands="COMMAND"

(mandatory, default='')

The list of commands to execute, which is a semicolon-separated string defining the commands to execute. Accepted values are:

  • PROCESS_CREATION: to process project creation on client-side. With this option, Data Providers runs on the client side. the results are then sent to the server, which will perform the result analysis and will import data into the database.

  • DELEGATE_CREATION: to send the project settings to the server to request a project creation

  • GENERATE_CONF_PARAMETERS: to generate the command line options associated to all parameters found in the specified configuration file. It requires the 'projectConfFile' option to be defined.

  • CHECK_MODELS: to check the validity of a model’s configuration. It requires the 'outputCheckModelsFile' option to be defined.

  • GENERATE_OUTPUT: to generate the output data and statistics of the project’s creation. It should always be called after all other commands.

General

-n "MyProject", --name="MyProject"

(mandatory, default='')

Defines the name of the project that will be created.

-w "ANALYTICS", --wizardId="ANALYTICS"

(mandatory, default='')

The id of the wizard used to create the project.

--branch="MyBranchName"

(optional, default='main')

Defines the project branch onto which the analysis will be executed. It is not possible to create branches from command line, only run analysis on existing branches.

--group="MyGroup"

(optional, default='')

Defines the group that the project belongs to. Projects from the same group are displayed together in the project portfolios and the group can optionally be rated as a whole. Note that you can specify subgroups by adding a / in your group name: --group="prototype/phase1" will create a phase1 group under a prototype group.

-v "V1", --version="V1"

(optional, default='null')

Defines the label used for the version of this project. If not specified, the version pattern parameter is used to generate the version label instead.

--versionPattern="V#.N#"

(optional, default='null')

Defines the pattern used to label the version automatically if no version parameter was passed.

The versionPattern parameter allows specifying a pattern to create the version name automatically for every analysis. It supports the following syntax:

  • #N#: A number that is automatically incremented

  • #Nn#: A number that is automatically incremented using n digits

  • #Y2#: The current year in 2-digit format

  • #Y4#: The current year in 4-digit format

  • #M#: The current month in two digit format

  • #D#: The current day in two digit format

  • #H#: The current hour in 24-hour format

  • #MN#: The current minute in two digit format

  • #S#: The current second in two digit format

Any character other than # is allowed in the pattern. As an example, if you want to produce versions labelled build-198.2013-07-28_13h07m (where 198 is an auto-incremented number and the date and time are the timestamp of the project creation), you would use the pattern: build-#N3#.#Y4#-#M#-#D#_#H#h#MN#m
--versionDate="YYYY-MM-DDTHH:MM:SS"

(optional, default='actual analysis time')

Allows specifying a date for the version that is different from the current date. This is useful when the charts on your dashboard haves axes or intervals that show dates instead of version names. Note that for every new analysis, the date must be after the date of the previous analysis.

--color="rgb(130,196,240)"

(optional, default='randomly assigned')

Defines the color used to identify the project in the Squore user interface after its creation. The numbers define the numbers define the values for red, green and blue respectively. Note that if you do not specify a color on the command line, a random color will be picked.

-b "true|false", --autoBaseline="true|false"

(optional, default='true')

Allows to build a baseline version that will not be overwritten by a subsequent analysis. When set to false, every analysis overwrites the previous one, until a new baseline is created. If not set, this parameter defaults to true.

--useLastParams="true|false"

(optional, default='false')

Allows to reuse all the parameters from the last known analysis on the project, whether it was executed from GUI, API or command line. Providing additional parameters will allow you to override the corresponding ones from last analysis.

--sendClientCredentials="true|false"

(optional, default='false')

Allows sending credentials defined on client side to Squore Server. Only useful when using DELEGATE_CREATION command to avoid providing un-obfuscated credentials in command line, when those are not defined on Squore Server.

Repository Connectors and Data Providers

-r "type=REPOTYPE,opt1=value1,opt2=value2", --repository="type=REPOTYPE,opt1=value1,opt2=value2"

(optional, multiple)

Used to specify repositories for sources. For more information about repositories syntax, refer to Repository Connectors. When using several source code repositories, each one must have an alias=NodeName parameter that is used to create a folder containing the source code for the repository in the Artefact Tree.

-d "type=DPName,dp_opt=dp_opt_value", --dp="type=DPName,dp_opt=dp_opt_value"

(optional, multiple)

Used to specify information for Data Providers. For more information about individual Data Provider syntax, refer to Data Providers.

-sub "true|false", --subFoldersAsVersions="true|false"

(optional, default='false')

Loops on the repository path to create a version for each sub-folder using the sub-folder name as the version name. This option is only supported when using the FROMPATH Repository Connector.

Team

-q "mike,DEVELOPER;peter,PROJECT_MANAGER", --teamUser="mike,DEVELOPER;peter,PROJECT_MANAGER"

(optional, default='')

This semicolon-separated list of login,projectRoleID pairs is used to define a list of users who will be able to access the project when it is created.

Note that this option is taken into account when creating a new project but is ignored when creating a new version. In order to edit the list of users in a project team, you must use the Squore web interface.

Refer to the list of available projectRoleIDs in Squore by clicking Administration > Roles. This option can be combined with the teamGroup parameter if needed.

-g "devUsers,DEVELOPER;management,GUEST", --teamGroup="devUsers,DEVELOPER;management,GUEST"

(optional, default='')

This semicolon-separated list of group,projectRoleID pairs used to define a list of groups who will be able to access the project when it is created.

Note that this option is taken into account when creating a new project but is ignored when creating a new version. In order to edit the list of groups in a project team, you must use the Squore web interface.

Refer to the list of available projectRoleIDs in Squore by clicking Administration > Roles. This option can be combined with the teamUser parameter if needed.

Forms

-t "TAGNAME=tagValue", --tag="TAGNAME=tagValue"

(optional, multiple)

If the wizard allows tags (i.e. project attributes), then use this parameter to inform the CLI of the tag values to use for this project.

-M "id=BETA_RELEASE,date=2015/05/31,PROGRESS=95", --milestone="id=BETA_RELEASE,date=2015/05/31,PROGRESS=95"

(optional, multiple)

Allows you to define a milestone in the project. This parameter accepts a date and a series of metrics with their values to specify the goals for this milestone. Note that this parameter allows you to add milestones or modify existing ones (if the ID provided already exists), but removing a milestone from a project can only be done from the web interface.

You can also define milestones in your project file using a Milestones element in the Wizard section:

<SquoreProjectSettings>
	<Wizard>
		<Milestones>
			<Milestone id="BETA_RELEASE" date="2015-05-31">
				<Goal id="PROGRESS" value="95" />
			</Milestone>
		</Milestones>
	</Wizard>
</SquoreProjectSettings>

Rulesets

--rulesetTemplate="my template"

(optional, default='null')

The name of the ruleset template created in the Ruleset Editor that should be used for this analysis. For more information about ruleset templates, consult the Getting Started Guide.

-um "/path/to/ruleset.xml", --updateModelFile="/path/to/ruleset.xml"

(optional, default='null')

The XML file listing the changes to be applied to the standard analysis model for this analysis. The XML file contains a list of rules with their status and categories, as follows:

<UpdateRules>
	<UpdateRule measureId="R_NOGOTO" disabled="true" categories="SCALE_SEVERITY.CRITICAL"/>
</UpdateRules>

This parameter is only read and applied when creating the first version of a project, for models where editing the ruleset is allowed. You may find it more flexible to work with named templates created in the Ruleset Editor and specified on the command line with the --rulesetTemplate parameter.

Output

-o "/path/to/output.xml", --outputFile="/path/to/output.xml"

(optional, default='null')

The absolute path to the output file generated by the analysis

-m "/path/to/validator.xml", --outputCheckModelsFile="/path/to/validator.xml"

(optional, default='null')

Defines the absolute path to the output check models file generated by the CHECK_MODELS command.

-print "true|false", --printOutput="true|false"

(optional, default='false')

Redirect the engine’s output to the standard output.

--keepDataFiles="true|false"

(optional, default='false')

Instructs Squore to keep or discard analysis files from old versions or only for the latest analysis. Note that this behaviour only affects disk space on the server, not the analysis results

-f "FILTER_OPTS", --filter="FILTER_OPTS"

(optional, default='')

This semicolon-separated string of triplets {artefactType,filterType,filterValue}. In order to export the measure LC, a DESCR info the indicator MAIN at application level, pass -f "APPLICATION,MEASURE,LC;APPLICATION,INFO,DESCR;APPLICATION,INDICATOR_LEVEL,MAIN;".

The artefact type ALL_TYPES and the filter types ALL_DEFECT_REPORTS, ALL_MEASURES, ALL_INDICATORS_LEVELS, ALL_INDICATORS_RANKS, ALL_BASE_FINDINGS, ALL_BASE_LINKS, ALL_COMPUTED_LINKS and ALL_INFOS can also be used, followed by an empty filter value. In order to export all measures at application level in the output file, pass the parameter --filter="APPLICATION,ALL_MEASURES,;". In order to export all indicators for all artefact types in the output file, pass the parameter --filter="ALL_TYPES,ALL_INDICATORS_LEVELS,;"

Other

-x "/path/to/project_conf.xml", --projectConfFile="/path/to/project_conf.xml"

(optional, default='null')

The XML file defining the project settings. When using a combination of a project file and some parameters passed from the command line, the command line parameters override the project file ones.

-ez "/path/to/project/data", --exportZip="/path/to/project/data"

(optional, default='null')

This parameter can be used to import a debug zip file as a new project. When this parameter is used, a new project is created using the parameters in the conf.xml file inside the debug package, with any other parameter passed on the command line overriding the ones from the configuration file. Instead of a debug zip file, you can pass an absolute path to a project data folder to start an analysis of all the version folders contained in that folder.

When using this option, you should pass --strictMode="false", -S false to disable some internal data integrity checks and change the project owner if needed using the --owner="admin", -O "admin" to se the new project owner (requires admin privileges).

This functionality is mostly used to test out how a project is rated in a different model, however it is not recommended for use in production since it will not replicate the following data from the old project to the new project:

  • All comments and discussion threads

  • Action Item statuses

  • History of changes in forms and relaxation comments

  • Relaxations and exclusions statuses of artefacts and findings

The rest of the parameters that you will pass to the Engine to create projects are specific to Repository Connectors and Data Providers and are detailed respectively in the Repository Connectors and Data Providers.

-?, --help

(optional, default='false')

Displays help and exits.

-?cmd, --help:commands

(optional, default='false')

Displays help about the available commands.