Squore uses a menus
folder in its configuration so you can add functionality that will
be available in the user interface to run external tools. These external scripts are launched in Squore Server's context, and can
therefore benefit from Squore's authentication and permission mechanism. They are launched from the web interface via a Tools menu visible to the users whose profile grants access to the Use External Tools feature.
Each external tool is defined within its own sub-folder in menus
and appears as a link in
the main Squore toolbar, as shown below:
The menu in the image above was added using a form.xml
and <filemene>form_en.properties</filemene> files.
Clicking the Execute button passes the user selections to a script called execute.tcl
.
<SQUORE_HOME>/configuration/menus/CreateDemo/form.xml
<?xml version="1.0" encoding="UTF-8"?> <tags baseName="Generic" multiUsers="false" users="demo" groups="demo" image="earth.png"> <tag type="multipleChoice" key="demo" displayType="comboBox" defaultValue="TECH_DEBT"> <value key="ISO9126" /> <value key="RISK_INDEX_C" /> <value key="RISK_INDEX_JAVA" /> <value key="TECH_DEBT" /> </tag> <tag type="booleanChoice" key="create_users" defaultValue="false"/> <tag type="multipleChoice" key="useAccountCredentials" displayType="radioButton" defaultValue="USE_ACCOUNT_CREDENTIALS" credentialType="USE_ACCOUNT_CREDENTIALS"> <value key="NO_CREDENTIALS" /> <value key="USE_ACCOUNT_CREDENTIALS" /> <value key="PERSONAL_CREDENTIALS" /> </tag> <tag type="text" key="username" credentialType="LOGIN" /> <tag type="password" key="password" credentialType="PASSWORD" /> </tags>
<SQUORE_HOME>/configuration/menus/CreateDemo/form_en.properties
FORM.GENERAL.NAME=Create Demo FORM.GENERAL.DESCR=Menu to create sample projects for demo. FORM.GENERAL.URL=http://www.squoring.com/ TAG.demo.NAME=Demo: OPT.ISO9126C.NAME=ISO9126 -- C OPT.RISK_C.NAME=Risk Index -- C OPT.RISK_JAVA.NAME=Risk Index -- Java OPT.TD_JAVA.NAME=Technical Debt -- Java OPT.ISO9126.NAME=ISO9126 -- C OPT.RISK_INDEX_C.NAME=Risk Index -- C OPT.RISK_INDEX_JAVA.NAME=Risk Index -- Java OPT.TECH_DEBT.NAME=Technical Debt -- Java TAG.create_users.NAME=Create Demo Users TAG.useAccountCredentials.NAME= OPT.NO_CREDENTIALS.NAME=No credentials OPT.USE_ACCOUNT_CREDENTIALS.NAME=Use my Squore credentials OPT.PERSONAL_CREDENTIALS.NAME=Define credentials TAG.username.NAME=Username TAG.password.NAME=Password
<SQUORE_HOME>/configuration/menus/CreateDemo/execute.tcl
set create_users [set ${::toolName}::create_users] set demo [set ${::toolName}::demo] if {$create_users == "true"} { create_user -name {Augustus Hill} -mail augustus.hill@domain.com -locale en augustus {1n/a5AsI5Rj6/m+MdX/tbCv9gSc=} [list admin users] create_role HEAD_OF_DEPARTMENT add_permission HEAD_OF_DEPARTMENT PROJECTS VIEW } switch $demo { "ISO9126" { #Earth create_project --name=Earth "--versionDate=2016-01-14T01:00:00" --wizardId=ISO9126 --color=rgb(130,196,240) -t COST=60 -t BV=80 -r type=FROMPATH,path=$squore_home/samples/c/Earth/V1 -d type=SQuORE,languages=c # Mars create_project --subFoldersAsVersions=true --name=Mars "--versionDate=2016-01-17T01:00:00" --wizardId=ISO9126 --color=rgb(245,30,14) -t COST=50 -t BV=30 -r type=FROMPATH,path=$squore_home/samples/c/Mars -d type=SQuORE,languages=c } "RISK_INDEX_C" { # Earth create_project --name=rEarth --version=V1 "--versionDate=2016-01-14T01:00:00" --wizardId=RISK --color=rgb(130,196,240) -t COST=60 -t BV=80 -d type=CPPCheck,xml=$squore_home/samples/c/Earth/V1/cppcheck.xml -r type=FROMPATH,path=$squore_home/samples/c/Earth/V1 } "RISK_INDEX_JAVA" { create_project --name=rFreemind --version=0.9.0 "--versionDate=2013-06-15T01:00:00" --wizardId=RISK --color=rgb(130,196,240) -t COST=60 -t BV=80 -d type=CheckStyle,xml=$squore_home/samples/java/Freemind/0.9.0/checkstyle.xml -d type=PMD,xml=$squore_home/samples/java/Freemind/0.9.0/pmd.xml -r type=FROMPATH,path=$squore_home/samples/java/Freemind/0.9.0 } "TECH_DEBT" { create_project --password=augustus --teamUser=augustus,HEAD_OF_DEPARTMENT\;demo,HEAD_OF_DEPARTMENT --login=jenkins-bangalore --wizardId=TD --name=android-vlc-remote --version=0.5.3 -r type=FROMPATH,path=$squore_home/samples/java/android-vlc-remote/0.5.3/src "--versionDate=2013-06-15T01:00:00" -d type=CheckStyle,xml=$squore_home/samples/java/android-vlc-remote/0.5.3/checkstyle.xml -d type=PMD,xml=$squore_home/samples/java/android-vlc-remote/0.5.3/pmd.xml -t TEAMSIZE=6 -t IMPLEMENTED_REQ=75 -t PLANNED_REQ=100 -t AUJOURDHUI=2013/06/15 -t BASE_END_DATE=2013/10/30 -t ESTIMATED_DELAY=1 -t PERCENT_NEW_FEATURES=90 -t ELOC_PRODUCTIVITY_PER_DEV=20 -t PERCENT_MAINTENANCE=10 -t BV=50 -t COST=30 --color=rgb(214,23,205) } }
The tags
element accepts the following attributes:
baseName
is the name of folder in Squore's addons folder that contains the executable tcl script. Set the value to Generic in order to
extend the generic framework that allows you to simply create users and projects.
multiUsers
defines whether only one running instance of the tool is allowed per user (true) or whether only one running instance at a time is allowed for the entire Squore Server (false).
users
: a semicolon-separated list of user logins. If specified, this
attribute limits the availability of the menu to the users explicitly listed.
groups
: a semicolon-separated list of user groups. If specified, this
attribute limits the availability of the menu to users belonging to the groups explicitly listed.
image
takes the path to an icon that is displayed next to the tool's name in the web interface
You can then add a series of tag
elements that follow the same specification as the one described in the section called “Attributes” to use as parameters on your custom page, with two extra types available:
decoration allows you to display an image followed by some text:
<tag type="decoration" image="custom-logo.png" style="width:500px"> This is the text that will be displayed next to the image. </tag>
file allows you choose a file to upload to the server:
<tag type="file" changeable="true" name="Upload this file: " key="file" defaultValue="" acceptedTypes="xls,xlsx"/>
The file is immediately uploaded on the server, and the TCL variable matching the specified key ($file
in the example above) is set to the absolute path of the uploaded file.
Consider the security implications of letting users upload arbitrary files to the server running Squore before using the file upload functionality.
Each tag
element accepts the attribute
required
(optional, default value: false), which allows marking the field as required and displays a red asterisk next to the field label.
The required
attribute is also valid in the form.xml
files
you create for your custom Data Providers and Repository Connectors.
The following variables are injected in the script execute.tcl
before execution:
outputDir: The directory associated with the menu.
tmpDir: The temporary directory associated with the menu
toolName: The name of the directory of the menu
toolBaseName: The name of the directory of the addons part of the menu
toolDir: The directory where the addons part of the menu can be found
toolkitDir: The directory where the Squore toolkit tcl scripts can be found
logFile: The name of the log file to use for displaying information
External Tools allow using several functions like create_project, which are covered in more details in Appendix B, External Tools Reference.