Additional Configuration

Forms

From the wizard’s first page, General Information, it is possible to define/overload metrics manually using forms.

Forms are also accessible outside the wizard, from the Explorer > Forms page.

Forms are defined inside the Bundle.xml file of the Wizards folder, using a series of tags and tag elements, as follows:

<tags>
	<tag type="numericValue" groupId="DECISION" measureId="BV" suffix=" FP" defaultValue="0" />
	<tag type="booleanChoice" groupId="DECISION" measureId="CRIT" defaultValue="false" />
	<tag type="multipleChoice" measureId="STATUS" defaultValue="SNAPSHOT" displayType="radioButton">
		<value key="SNAPSHOT" value="1" />
		<value key="VALIDATION" value="2" />
		<value key="RELEASE" value="3" />
	</tag>
	<tag type="multipleChoice" measureId="DEPART" defaultValue="HR" displayType="comboBox">
		<value key="ACCOUNT" value="1" />
		<value key="HR" value="2" />
		<value key="SALES" value="3" />
		<value key="OTHER" value="4"/>
	</tag>
	<tag type="date" measureId="SPRINT_START" defaultValue="TODAY" />
	<tag type="date" measureId="SPRINT_END" defaultValue="2012/12/31" />
</tags>

User specified forms values are handled by Squore just like any other measures provided by Data Providers. These values are imported as base measures as long as the model contains a definition that uses the same measure ID.

Descriptions for your tag and tags groups should be specified in a .properties file included in your description bundle.

TAG.BV.NAME=Project Business Value
TAG_GROUP.DECISION.NAME=Important Decision Criteria
TAG.CRIT.NAME=is Critical
TAG_GROUP.decision.NAME=Important Decision Criteria
TAG.STATUS.NAME=Status:
TAG.DEPART.NAME=Department:
TAG.SPRINT_START.NAME=Sprint Start:
TAG.SPRINT_END.NAME=Sprint End:

The image below shows how tags defined in the wizard appear to a Squore user when creating a version of a project:

CFG wizardTags
Figure 1. Project tags in the project wizard

This other image shows how tags defined in the wizard appear to a Squore user when in the Forms tab of the explorer:

CFG forms
Figure 2. Project tags in the Explorer

The tags element accepts the following attributes:

  • groupId (optional, default: none) to define the ID of the group containing the tags defined under. When defined, it allows for the following additional attribute:

    • opened (optional, default: false) to specify whether the group is collapsed or un-collapsed by default.

    Add a TAG_GROUP.<groupId>.NAME entry in one of your model .properties file in order to translate this ID.

  • roles (optional, default: all) to define the specific list of roles that can edit the tags defined under.

    Provided roles must have the associated Modify Artefacts Attributes permission, otherwise users still won’t be able to edit the form(s).

The tag element accepts the following attributes:

  • type (mandatory) defines the type of information accepted as value for this tag. The following values are accepted:

    • text for free text entry

    • numericValue for numbers

    • date for dates

    • booleanChoice for a boolean

    • multipleChoice for offering a selection as a list

  • inverted (optional, if booleanChoice = true) allows you to put the text on the other side of the checkbox

  • displayType (optional) allows specifying the display type in the Forms tab and the project wizard. The following values are accepted:

    • comboBox for tags of type multipleChoice

    • radioButton for tags of type multipleChoice

    • input for tags of type text

    • textarea for tags of type text

    Tags of type date automatically show a date picker and tags of type booleanChoice are rendered as a checkbox. These types do not support the use of displayType.

  • name (optional) is the label used to describe the attribute in the UI.

  • measureId (mandatory) is the ID of the measure that the value is passed to.

    By default, the standard translation of the measureId is displayed in the web interface. If you want to have different text displayed for the tag specifically, add a TAG.<measureId>.NAME entry in one of the .properties files of your model.

  • groupId (optional, default: none) to define the ID of the group into which this measure under must be added.

    Add a TAG_GROUP.<groupId>.NAME entry in one of your model .properties file in order to translate this ID.

  • roles (optional, default: all) to define the specific list of roles that can edit the tags defined under.

    Provided roles must have the associated Modify Artefacts Attributes permission, otherwise users still won’t be able to edit the form(s).

  • suffix (optional, default: empty) is the label displayed after the value of the metric in the UI

  • defaultValue (optional, default: empty) is the default value of the attribute if not specified by the user. In the case of a date, the value TODAY() can be used to automatically use today’s date as the default value.

  • group (optional) helps group various tags by category visually in the Forms tab of the Explorer.

  • targetArtefactTypes (optional, default: APPLICATION) allows associating the attribute to other types of artefacts (more on this below).

Note: A tag element can appear within a wizard element or at Bundle level. In case two tag elements impacting the same measureId exist at both levels, the definition within the wizard element overrides the one at Bundle-level.

All tags described above are defined at application level. They are visible and editable when creating a project and in the Form tab of the Explorer if the project is in draft mode. It is possible to associate an attribute to any artefact type by using the targetArtefactTypes attribute, as shown below:

<tag groupId="PROJECT_STATUS" targetArtefactTypes="APPLICATION;SOURCE_CODE;DOCUMENTATION;FOLDER" type="booleanChoice" measureId="TESTED" defaultValue="false" />

Repository Connectors

You may specify whether users can use any available Repository Connectors, which is the default one and what the default values are for each Repository Connector using the repositories element in your wizard definition . If you want to allow any Repository Connector in Squore, do not specify any repositories element, which is the equivalent of using:

<repositories all="true" hide="false" />

  • all instructs Squore to show all Repository Connectors.

  • hide allows hiding the Repository Connector selection fields when going through the wizard in the web UI. Note that Squore automatically ignores the value of hide if it detects that at least one of the Data Providers in the project needs sources.

In order to restrict which Repository Connectors are available, use:

<repositories all="false" hide="false">
	<repository name="FROMPATH" checkedInUI="true" >
		<param name="path" value="/media/sources" />
	</repository>
	<repository name="FROMZIP" />
	<repository name="SVN" />
</repositories>

The repository element accepts the following attributes:

  • name (mandatory) is the name of the Repository Connector to be used. It must correspond to one of the Repository Connectors defined in your configuration (by default under <SQUORE_HOME>/configuration/repositoryConnectors/[name]).

  • checkedInUI (optional, true|false, default: false, only one can be set to true) defines whether the Repository Connector is selected by default in the web interface. Note that this parameter has no effect on project creations from the command line.

  • projectStatusOnFailure (optional, default: ERROR) defines what status the project ends in when this Repository Connector produces an error. The following values are allowed:

    • IGNORE

    • WARNING

    • ERROR

Note: Each repository element accepts name/value pairs as parameters in which you can override the values defined in the Repository Connector’s default configuration.

The following image illustrates how the configuration above is displayed in Squore:

CFG wizardRCs
Figure 3. Repository Connector Selection Screen

Data Providers

You may specify whether all or some Data Providers are available, and provide their default settings when the project wizard runs.

Data Providers are specified using the tools element:

<tools show="LIST" expandedInUI="true">
	<tool name="SQuORE" optional="false" projectStatusOnFailure="warning" expandedInUI="true" />
	<tool name="CheckStyle" optional="true" projectStatusOnFailure="error" checkedInUI="false" />
	<tool name="Findbugs_auto" optional="true" projectStatusOnFailure="ignore" />
</tools>

Where:

  • show allows you to configure which Data Providers are to be displayed in the wizard. Accepted values are:

    • LIST (default) to only display the Data Providers defined in the list below.

    • AUTO to display all the Data Providers compatible with the selected model, whether they are in the list or not.

    • AUTO_AND_GENERATED to display all the Data Providers compatible with the selected model, whether they are in the list or not, plus the incompatible ones created using the Data Provider Editor.

    • ALL to display all and every Data Providers.

  • expandedInUI allows you to expand the list of available Data Providers when viewing the wizard from the web UI.

The tool element accepts the following attributes:

  • name is the name of the Data Provider to be used. It must correspond to one of the Data Providers defined in your configuration (by default under <SQUORE_HOME>/configuration/tools/[name]).

  • optional (true|false, default: false): When set to false the Data Provider is always included in the analysis, even when not explicitly called from the command line. It also prevents from unchecking it in the web interface. When set to true, the Data Provider is available but not automatically included in an analysis.

  • projectStatusOnWarning and projectStatusOnFailure (ignore|warning|error, default: warning) specify the status to give the analysis if the Data Provider execution finishes in WARN or ERROR/FATAL level.

    • When set to ignore, the project ends in the Created state.

    • When set to warning, the project ends in the Warning state, which means that a draft is created (even if you required a baseline version to be created).

    • When set to error, the project ends in the Error state, which means that no new version is created.

  • checkedInUI (true|false, default: true) defines whether the Data Provider is selected by default in the web interface. Note that this parameter has no effect on project creations from the command line.

  • expandedInUI (true|false, default: false) defines whether the Data Provider’s settings panel is expanded (true) or collapsed (false) by default in the web interface. Note that this parameter has no effect on project creations from the command line.

  • deprecated (optional, default: false) to remove a Data Provider from the list of available Data Providers for new projects, while keeping it available for existing projects that already have used it.

Each tool element accepts name/value pairs as parameters in which you can override the values defined in the Data Provider’s default configuration. These parameters can be shown or hidden in the web UI, as shown below.

<tool name="Findbugs_auto">
	<param name="java_path" value="/usr/bin/java" hide="true" />
</tool>

The param element accepts the following attributes:

  • value (optional, default: empty string) to define the parameter value.

  • hide (optional, default: false) to hide the parameter.

  • availableChoices (optional) to define the list of available choices for the parameter. It can only be used when the parameter is of type multipleChoice and optionTitle attribute is defined.

The following image illustrates how the configuration above is displayed in Squore:

CFG wizardDPs
Figure 4. Data Provider Selection Screen

Milestones

Milestones and goals for your project can be configured in the Wizard Bundle. A milestone has a name, a date, and allows you to set a goal for one or more metric in your project. You can configure your wizard to allow users to create milestones and define goals from scratch, or you can define your company milestones and objectives to ensure that they are part of every project created with this wizard.

In order to add support for milestones to your model, configure your wizard to allow users to create milestones and goals:

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<wizard wizardId="ANALYTICS" versionPattern="v#N1#" img="../../Shared/Wizards/squore_logo.png" hideRulesEdition="false">
		<milestones canCreateMilestone="true" canCreateGoal="true">
			<goals displayableFamilies="ANALYTICS_GOALS" />
		</milestones>
	</wizard>
</Bundle>

The milestones element allows users to create milestones in the project wizard (canCreateMilestone="true") and also set goals (canCreateGoal="true"). The goals can be set for metrics of the GOALS family only in this example (displayableFamilies="ANALYTICS_GOALS").

The result in the web UI is the following:

ALL UsingMilestones 07 wizardFreeztyle
Figure 5. A wizard allowing users to create milestones freely during an analysis

When creating a new project, a user decides to create a Sprint 1 milestone with one objective of 500 for the Technical Debt indicator. Other goals can be set, for the other metrics in the project that belong to the ANALYTICS_GOALS family listed in the dropdown list at the bottom of the table.

If you have company-wide milestones and objectives that need to be set for every project created with the wizard, you can specify the goals directly. Milestones can also be marked as mandatory or optional:

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<wizard wizardId="ANALYTICS_WITH_MILESTONES" versionPattern="v#N1#" img="../../Shared/Wizards/squore_logo.png" hideRulesEdition="false">
		<milestones canCreateMilestone="true" canCreateGoal="true">
			<goals displayableFamilies="GOALS">
				<goal measureId="TECH_DEBT" mandatory="true" />
				<goal measureId="ISSUE_BLOCKER" mandatory="true" />
				<goal measureId="ISSUE_CRITICAL" mandatory="true" />
				<goal measureId="ROKR_SUBSET" mandatory="true" />
			</goals>
			<milestone id="REQUIREMENT_FREEZE" mandatory="true">
				<defaultGoal measureId="TECH_DEBT" value="0" />
				<defaultGoal measureId="ISSUE_BLOCKER" value="1" />
				<defaultGoal measureId="ISSUE_CRITICAL" value="30" />
				<defaultGoal measureId="ROKR_SUBSET" value="1" />
			</milestone>
			<milestone id="INFRASTRUCTURE_FREEZE" mandatory="true">
				<defaultGoal measureId="TECH_DEBT" value="0" />
				<defaultGoal measureId="ISSUE_BLOCKER" value="1" />
				<defaultGoal measureId="ISSUE_CRITICAL" value="50" />
				<defaultGoal measureId="ROKR_SUBSET" value="1" />
			</milestone>
			<milestone id="CODE_FREEZE" mandatory="true">
				<defaultGoal measureId="TECH_DEBT" value="0" />
				<defaultGoal measureId="ISSUE_BLOCKER" value="1" />
				<defaultGoal measureId="ISSUE_CRITICAL" value="90" />
				<defaultGoal measureId="ROKR_SUBSET" value="0.5" />
			</milestone>
			<milestone id="BETA_RELEASE" mandatory="false">
				<defaultGoal measureId="TECH_DEBT" value="1" />
				<defaultGoal measureId="ISSUE_BLOCKER" value="1" />
				<defaultGoal measureId="ISSUE_CRITICAL" value="95" />
				<defaultGoal measureId="ROKR_SUBSET" value="0.3" />
			</milestone>
			<milestone id="RELEASE" mandatory="true">
				<defaultGoal measureId="TECH_DEBT" value="1" />
				<defaultGoal measureId="ISSUE_BLOCKER" value="1" />
				<defaultGoal measureId="ISSUE_CRITICAL" value="100" />
				<defaultGoal measureId="ROKR_SUBSET" value="0" />
			</milestone>
		</milestones>
	</wizard>
</Bundle>

When creating a new project, the predefined goals are filled in the web interface, and you can still add a Beta Release milestone (using the default values specified in the wizard bundle) if needed by using the \+ icon:

ALL UsingMilestones 08 predefined
Figure 6. A project wizard with preconfigured milestones and goals

The milestones element accepts the following attributes:

  • canCreateMilestone (optional, default: true) defines if a button is available in the web UI to add new milestones

  • canCreateGoal (optional, default: true) defines if a button is available in the web UI to add new goals for milestones

  • hide (optional, default: false) allows hiding the milestones pane of the wizard in the web interface

  • skipUiValues (optional, default: false) allows to choose the default status of the checkbox "Only use milestones and goals provided by Data Providers" in the user interface. No matter what is set by default, if necessary the user can modify the milestones information in the interface

  • changeableMode (optional, default: true) allows you to grey out the "Only use milestones and goals provided by Data Providers." checkbox in the user interface. Users can no longer modify milestones from the user interface

The goals element accepts the following attribute:

  • displayableFamilies (optional, default: no filter) allows filtering the list of metrics listed in the web interface when adding a goal. The value of the parameter is a family name, and when specified, only metrics of this family will be available as goals from the web interface.

The goal element allows preconfiguring your goals in the project and accepts the following attributes:

  • measureId (mandatory) is the ID of the metric to use as a goal

  • mandatory (optional, default: false) defines whether users can remove a goal from the web interface

The milestone element accepts the following attributes:

  • id (mandatory) is the unique identifier of the milestone in the model

  • defaultDate (optional, default: none) is the date used for the milestone by default.

  • mandatory (optional, default: false) defines whether users can remove a milestone from the web interface.

The defaultGoal element accepts the following attributes:

  • measureId (mandatory) is the unique identifier of the metric to use as goal

  • value (mandatory) is the default value for the goal.

For a complete example of how to use milestones in a Squore project, consult Milestones Tutorial.

Notifications

E-mail notifications are configured in the wizard’s Bundle.xml file. Their configuration consist of 3 nested levels:

  • First level is the condition to trigger the notification

  • Second is the notification that will be available in the GUI

  • Third is the template to describe the e-mail body and user’s roles

Default draft notification definition
<onDraft>
    <notification id="NEW_BUILD_OWNER">
            <template descrId="NOTIFY_DRAFT" roles="OWNER"/>
    </notification>
    <notification id="NEW_BUILD_PROJECT_MANAGER" statuses="SUCCESS">
            <template descrId="NOTIFY_DRAFT" roles="PROJECT_MANAGER"/>
    </notification>
    <notification id="NEW_BUILD_TEAM" statuses="SUCCESS">
            <template descrId="NOTIFY_DRAFT" roles="DEVELOPER;TESTER;GUEST"/>
    </notification>
    <notification id="BUILD_WARNING" statuses="WARNING">
            <template descrId="NOTIFY_WARNING" roles="OWNER;PROJECT_MANAGER" />
    </notification>
</onDraft>

Available conditions are:

  • onBaseline to set up notifications when baseline operation is successful.

  • onDraft to set up notifications when draft analysis is successful or ends-up with warnings.

  • onFailure to set up notifications when a build operation fails or is cancelled.

The notification element accepts the following attributes:

  • id (mandatory) to define the id of the notification.

  • activeByDefault (optional, default:false) to define whether the notification is checked in the GUI by default.

  • statuses (optional, default:all) to define the status for which the notification is valid. Accepted values are:

    • SUCCESS, only for onBaseline and onDraft conditions.

    • WARNING, only for onDraft condition.

    • ERROR, only for onFailure condition.

    • CANCELLED, only for onFailure condition.

The template element accepts the following attributes:

  • descrId (mandatory) to define the id of the description that contains the notification content.

  • roles (optional, default:all) to define roles for which the template applies to.

  • groups (optional, default:all) to define groups for which the template applies to.

  • onlyIf (optional, default:none) to define a computation to evaluate whether the template will be applied or not. If the result is more than 0 the template is applied and the notification sent. Consult Expressions Syntax for more information about the supported computation syntax.

Multiple template elements can be included in the notification element, allowing to define specific content depending on the users roles, groups or computation.

If multiple templates are available for a given user and scenario, only one notification will be sent, the first one according to the Wizard’s definition order.

The notification content is defined in a description file *.properties, like any other descriptions (Descriptions syntax).

It is possible to include model entities values in the notification content using the syntax, ${<computation>} (Expressions Syntax), as follows:

Default draft notification content defined in description file
TEMPLATE.NOTIFY_DRAFT.DESCR=<p>A new draft of ${PROJECT_NAME()} is available at ${BUILD_URL()}</p><p>Version: ${VERSION_NAME()}<br/>Date: ${VERSION_DATE()}<br/>${NAME(LEVEL)} Rating: ${NAME(LEVEL(LEVEL))}</p><br/><p>This message was sent automatically by Squore, contact your administrator for more information.</p>