Getting Started

Option 1: Out-Of-the-Box

Download and extract the ready-to-use distribution. On Windows you might simply run the pre-built executable eclipse.exe. On Linux (and Windows, if you prefer to not use the executable) start Skalli from a shell with

java -Dosgi.compatibility.bootdelegation=true -Declipse.ignoreApp=true -Dosgi.noShutdown=true 
-Dequinox.ds.print=true -Djetty.home=./jetty -Dlogback.configurationFile=./jetty/etc/logback.xml 
-jar plugins/org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar -clear -console -consoleLog 
-configuration ./configuration

Note, in either case you need a Java 6 runtime (both 32 and 64 bit VMs are supported).

Navigate to http://localhost:8080 and log in with guest/guest or admin/admin. Some sample data is already included, e.g. type skalli in the search field (or enter http://localhost:8080/projects?query=skalli as URL) to obtain the detail page of the Eclipse Skalli project.

Option 2: Installing Jetty Web RT

Download the latest Jetty Web Starter Kit and unpack it (e.g. to /opt/jetty). Note, you need a 32 bit Java VM to run Jetty because it is based on a 32 bit Eclipse platform.
Configure Jetty [1] according to your needs or copy the etc folder from o.e.s.target/jetty to the etc folder of the Jetty installation as a start.
Run Jetty (note: on Windows use rtweb.exe; start.bat seems to be broken in Jetty 3.7.1).
Continue with deployment (Option 3).

Option 3: Deploying Skalli with P2

In the OSGi console enter the following commands:

provaddrepo https://hudson.eclipse.org/hudson/job/skalli/lastSuccessfulBuild/artifact/org.eclipse.skalli.site/target/site/
provlg
provinstall org.eclipse.skalli.orbit.feature.feature.group <iuv>
provinstall org.eclipse.skalli.feature.feature.group <iuv>

<iuv> is the corresponding version of the feature as displayed by provlg.

Restart the server
Open http://localhost:8080 and log in with admin/admin

By default, Skalli is configured to use a file system based storage mechanism for project data (see the storage directory of your Jetty installation). You may copy some test data from org.eclipse.skalli.target/workdir/storage to your storage folder as a start.

Tutorials

How to Implement Skalli Extensions

You can write your own extensions for Skalli. There are several extension points, e.g. you can add custom properties to the project model, provide a form to edit them, show them in an info box on a project's detail page, pass them to Lucene to search for them, or translate them into REST format. The extension mechanism is based completely on OSGi Declarative Services, with which Eclipse developers should be quite familiar.

There are currently the following tutorials available:

The first shows how to implement a simple Hello World info box, while the second demonstrates everything you need to know if you want to enhance the project model and integrate smoothly with all the services and UIs. The source code of these tutorials is part of the Skalli source code, see bundles org.eclipse.skalli.ext.simplehelloworld and org.eclipse.skalli.ext.helloworld, respectively.

Configuration

Most of the various configuration settings of Skalli can be managed via REST API calls. For Firefox we recommend to use the RESTClient) add-on, but curl or another suitable web console should do the job as well.

Choosing the Storage Service

Skalli is not bound to a certain storage mechanism but searches the runtime for suitable implementations of the interface org.eclipse.skalli.api.java.StorageService. If not explicitly specified, Skalli will use a file system based storage mechanism by default.

In order to switch to an alternative storage mechanism, you can either

define the system property skalli.storageService and set it to the qualified class name of a storage service implementation.
define the property skalli.storageService in the configuration file skalli.properties which must be added to the root directory of the org.eclipse.skalli.core bundle. If you don't want to change that bundle, create a fragment with org.eclipse.skalli.core as fragment host and add the property file there. You may also download a blueprint from here: [2]. The value of the property again is the class name of the service implementation.

Using File System Based Storage: Setting the Working Directory

If you are using the file system based storage mechanism, you should define a working directory. The file system storage service will use that directory for all project related data and customization settings.

The working directory can be specified

by defining the system property workdir=<path-to-working-directory>
by defining a property workdir in the configuration file skalli.properties (see above)

The value of the property in both cases must be the absolute path of the working directory. If workdir is not set explicitly the current directory is used as default.

Configuring LDAP

Skalli is able to use LDAP to retrieve information about users, e.g. to be able to select and manage committers for projects. Note, LDAP is not used to authenticate users accessing Skalli! By default, Skalli is configured to delegate authentication to the web container (FORM-based authentication).

For defining LDAP access you need to issue a PUT request to /api/config/ldap.

PUT https://<your-host>/api/config/ldap

<ldap>
  <username>skalli@example.org</username>
  <password>verysecretpassword</password>
  <ctxFactory>com.sun.jndi.ldap.LdapCtxFactory</ctxFactory>
  <hostname>ldap://ldap.example.org:389</hostname>
  <usersGroup>CN=Users,DC=example.org</usersGroup>
</ldap>

The given configuration is only an example. Adapt the parameters to your needs.

Notes:

<usersGroup> defines the objects to search (users), i.e. is passed as name argument to javax.naming.ldap.LdapContext#search(Name name, String filter, SearchControls cons).

Switching between LDAP and a Local User Store

If you prefer to use a Skalli internal store to manage user information like full name and email address instead of using an LDAP server, the LDAP client in Skalli has to be disabled. To do so, issue a REST request to resource /api/config/userStore.

PUT https://<your-host>/api/config/userStore

<userStore>
  <type>local</type>
  <useLocalFallback>false</useLocalFallback>
</userStore>

Notes:

<type> determines whether LDAP or a local user store should be used to retrieve user information. Allowed values are local and ldap (which is the default).
<useLocalFallback> determines whether the local user store should be used as a fallback if no suitable LDAP server is available (only relevant if type ldap is set). Allowed values are true and false.

Users are stored in the directory <workdir>/storage/User (if the file system based storage is used). Each user is persisted in a separate XML file named <userId>.xml in this directory.

Example of a <userId>.xml file:

<org.eclipse.skalli.common.User>
  <userId>ad</userId>
  <firstname>Arthur</firstname>
  <lastname>Dent</lastname>
  <email>arthur.dent@milliways.com</email>
  <telephone>+000 314159265</telephone>
  <room>42</room>
  <location>End of the Universe (and then right)</location>
  <department>kitchen</department>
  <company>Milliways - The Restaurant at the End of the Universe</company>
  <sip>sip:arthur.dent@milliways.com</sip>
  <detailsMissing>false</detailsMissing>
</org.eclipse.skalli.common.User>

Notes:

userId must be the id of an authenticated user of your web container (Jetty, Tomcat etc.). For example, in Jetty you can define user ids in etc/realm.properties.
There is currently no UI to manage users this way.

Configuring Administrator Users

Skalli administrators are allowed to do more than normal users, e.g. they are allowed to:

edit all projects
delete projects
see issues for all projects
configure a Skalli instance

Skalli adds the command admin to the OSGI console that allows to list, add and remove Skalli administrators:

skalli admin [-list] [-add <admin_id>] [-remove <admin_id>] - maintain set of user with administrative permissions

If you for example want to add the user skalliadmin to the group of administrators type

osgi> skalli admin -add skalliadmin

. Administrators are persisted in the directory <workdir>/storage/Group (if file system based storage is enabled).

User Details Links

Defining the URL pattern for links to pages showing details about committers, contributers, members etc. In the Team info box on a project's detail page clicking on the name of a committer leads to the user's detail page.

PUT https://<your-host>/api/config/view/userdetails

<userdetails>
  <url>http://www.eclipse.org/projects/lists.php?list=projectsforcommitter&param=%s</url>
</userdetails>

Notes:

%s is a placeholder for the user's identifier.
The example above generates links for Eclipse committers.

Proxy

If you are behind a firewall you should configure the proxy to use for outbound HTTP connections (e.g. to allow Skalli checking URLs defined by projects). For that you need to issue a REST request to /api/config/proxy.

Example:

PUT https://your-host>/api/config/proxy

<proxy>
  <host>proxy</host>
  <port>8080</port>
  <nonProxyHosts>*.example.org;*.example.com;non-proxy-host</nonProxyHosts>
</proxy>

Automatic URL Inference from SCM Location

A Skalli project can enable the "Development Infrastructure" extension to provide information about the project's source code repository, continuous integration build (e.g. on a Hudson/Jenkins server), bug tracker used to track issues etc. Additionally, a link to a browsable front-end of the source code repository can be entered (e.g. a link to a gitweb server), as well as a link to a code review system like Gerrit.

However, Skalli also supports a mechanism that allows defining automatic mappings between the source repository of a project (in Maven SCM notation) and web sites for browsing of the source code, reviewing of commits etc.

For that you need to issue a PUT request to /api/config/devInf/scmMappings.

Example:

PUT https://<your-host>/api/config/devInf/scmMappings

<?xml version="1.0" encoding="UTF-8" ?>
<scmMappings>
  <scmMapping>
    <id>review.gerrit.example.org</id>
    <purpose>review</purpose>
    <pattern>^scm:git:git://(git\.example\.org(:\d+)?)/(.*)\.git$</pattern>
    <template>http://{1}:8080/#project,open,{3},n,z</template>
    <name>Gerrit Code Review</name>
    <provider>git</provider>
  </scmMapping>
  <scmMapping>
    <id>browse.gitweb.example.org</id>
    <purpose>browse</purpose>
    <pattern>^scm:git:git://(git\.example\.org(:\d+)?)/(.*\.git)$</pattern>
    <template>http://{1}:50000/git/?p={3}</template>
    <name>Browse Sources in GitWeb</name>
    <provider>git</provider>
  </scmMapping>
  <scmMapping>
    <id>browse.git.eclipse.org</id>
    <purpose>review</purpose>
    <pattern>^scm:git:git://git.eclipse.org/gitroot/(.+\.git)$</pattern>
    <template>http://git.eclipse.org/c/{1}/</template>
    <name>Browse Sources on Eclipse.org</name>
    <provider>git</provider>
  </scmMapping>
</scmMappings>

The first entry for example defines a mapping between Git repositories matching the regular expression (git\.example\.org(:\d+)?)/(.*)\.git (meaning: all Git repositories hosted by the server git.example.org) and a Gerrit code review system (purpose review). When a project defines an SCM location matching the given pattern, Skalli creates a link from the given link template by replacing the numbered variables with the content of the corresponding regular expression groups extracted from the SCM location. In the example above, {1} stands for the first group, i.e. the host git.example.org (without port), while {3} denotes the third group, i.e. the repository name. For example, an SCM location like scm:git:git://git.example.org/myproject.git would map to http://git.example.org:8080/#project,open,myproject,n,z.

For more details about Java regular expressions and groups refer to [3].

Notes:

The mechanism described above is not limited to Git as SCM system. It is based on a simple regular expression matching/replacing mechanism and should be applicable to all kinds of SCM systems.
The purpose of a mapping defines for which kind of links a mapping should be applied. Predefined purposes are:
browse

for a link to a browsable front-end of an SCM system like gitweb

review

for a link to a code review system like Gerrit

activity

for a link to a graphic visualizing of the commit activity of a project

activitydetails

for a link to details about the commit activity of a project

create_bug

for a link that allows to create bugs in a bug tracking system
Skalli Extensions are free to define additional purposes.
The id can be defined freely, but must be unique in the list of mappings.
The name tag defines the label Skalli should render for mapped links in the Development Infrastructure info box.
The numbered variable {0} is replaced by the project's symbolic name, e.g. with technology.skalli.

Mappings for Eclipse Projects

If you use Skalli primarily for managing of projects at eclipse.org, you might find the following mappings interesting:

<?xml version="1.0" encoding="UTF-8" ?>
<scmMappings>
  <scmMapping>
    <id>browse.git.eclipse.org</id>
    <purpose>review</purpose>
    <pattern>^scm:git:git://git.eclipse.org/gitroot/(.+\.git)$</pattern>
    <template>http://git.eclipse.org/c/{1}/</template>
    <name>Browse Sources on Eclipse.org</name>
    <provider>git</provider>
  </scmMapping>
  <scmMapping>
    <id>createBug.bugs.eclipse.org</id>
    <purpose>create_bug</purpose>
    <pattern>^https://bugs.eclipse.org/bugs/buglist.cgi?.*(product=[^&amp;]*).*</pattern>
    <template>https://bugs.eclipse.org/bugs/enter_bug.cgi?{1}</template>
    <name>Create Bugs on bugs.eclipse.org</name>
    <provider>bugtracker</provider>
  </scmMapping>
  <scmMapping>
    <id>activity.git.eclipse.org</id>
    <purpose>activity</purpose>
    <pattern>^scm:git:git://git.eclipse.org/gitroot/(.+\.git)$</pattern>
    <template>http://dash.eclipse.org/dash/commits/web-app/active-graph.cgi?project={0}</template>
    <name>Commits Activity Meter</name>
    <provider>git</provider>
  </scmMapping>
  <scmMapping>
    <id>activitydetails.git.eclipse.org</id>
    <purpose>activitydetails</purpose>
    <pattern>^scm:git:git://git.eclipse.org/gitroot/(.+\.git)$</pattern>
    <template>http://dash.eclipse.org/dash/commits/web-app/summary.cgi?company=y&amp;month=x&amp;project={0}</template>
    <name>Commits by Company by Month</name>
    <provider>git</provider>
  </scmMapping>
</scmMappings>

Automatic URL Inference from Mailing Lists

PUT https://<your-host>/api/config/info/mailingList

<mailingListMappings>
  <mailingListMapping>
    <id>listserv</id>
    <purpose>browse </purpose>
    <name>Browse</name>
    <pattern>^(.+)@listserv.example.org$</pattern>
    <template>https://listserv.example.org/{1}</template>
  </mailingListMapping>
  <mailingListMapping>
    <id>listserv.archive</id>
    <purpose>browse-archive</purpose>
    <name>Browse Archive</name>
    <pattern>^(.+)@listserv.example.org$</pattern>
    <template>https://listserv.example.org/archives/{1}</template>
  </mailingListMapping>
</mailingListMappings>

This mechanism works similar to the SCM mappings above. If a mail address is entered that matches the given pattern, then the template is evaluated and variables are replaced with the corresponding regular expression groups of the pattern. For example, myproject@listserv.example.org would give the URL https://listserv.example.org/myproject to browse the latest content and https://listserv.example.org/archives/myproject to browse an archive of the mailing list, respectively. The defined name is rendered as link label. You may register mappings for different mailing list providers in parallel.

Predefined purposes:

browse

a link to a browsable view of the latest content of the mailing list

browse-archive

a link to a browsable archive of the mailing list

subscribe

a link that allows to subscribe to the mailing list

unsubscribe

a link that allows to unsubscribe from the mailing list

Note, extensions are free to define additional purposes. The Mailing List info box ignores the purpose and just renders all links that match the entered mailing list(s).

Mappings for Eclipse Projects

If you use Skalli primarily for managing of projects at eclipse.org, you might find the following mappings interesting:

<mailingListMappings>
  <mailingListMapping>
    <id>listinfo.eclipse.org</id>
    <purpose>subscribe</purpose>
    <name>Subscribe/Unsubscribe</name>
    <pattern>^(.+)@eclipse.org$</pattern>
    <template>https://dev.eclipse.org/mailman/listinfo/{1}</template>
  </mailingListMapping>
  <mailingListMapping>
    <id>mhonarc.eclipse.org</id>
    <purpose>browse-archive</purpose>
    <name>Browse Archive</name>
    <pattern>^(.+)@eclipse.org$</pattern>
    <template>http://dev.eclipse.org/mhonarc/lists/{1}</template>
  </mailingListMapping>
</mailingListMappings>

Scheduling of Validation Jobs

Defining a schedule for the asynchronous validation of projects.

PUT https://<your-host>/api/config/core/validations

<validations>
    <validation>
        <schedule>
            <daysOfWeek>*</daysOfWeek>
            <hours>*/2</hours>
            <minutes>0</minutes>
        </schedule>
        <minSeverity>ERROR</minSeverity>
        <action>VALIDATE</action>
        <userId>homer</userId>
        <entityType>Project</entityType>
    </validation>
    <validation>
        <schedule>
            <daysOfWeek>MON</daysOfWeek>
            <hours>2</hours>
            <minutes>0</minutes>
        </schedule>
        <minSeverity>INFO</minSeverity>
        <action>QUEUE</action>
        <userId>homer</userId>
        <entityType>Project</entityType>
    </validation>
    ...
</validations>

The first entry validates all projects daily every second hour (e.g. a 0:00, 2:00, ...) and reports issues with at least severity ERROR (other possible values: INFO, WARNING, FATAL). The entries of <schedule> support crontab notation defining the minutes (tag <minutes>), hours (tag <hours>) and days of the week (tag <daysOfWeek>) when a validation should run. 24-hour format is used for <hours> (possible values: 0..23). The day of the week can be defined with numbers (0=Sunday,1=Monday,...,7=Sunday), long names (SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY), or short names (SUN, MON, TUE, WED, THU, FRI, SAT), respectively. Note that the names are handled case-insensitive, i.e. Sun, SUN and sun mean all the same.

Supported actions are

QUEUE

put all entities of the given <entityType> (currently supported values: Project) into the queue for entities to be revalidated. The validation is done asynchronously.

QUEUE_ALL

put all entities of all types into the queue for entities to be revalidated (<entityType> is ignored). The validation is done asynchronously.

VALIDATE

validates entities of the given <entityType> (currently supported values: Project). The validation is done synchronously. Note, depending on the number of entities to validate and validators to be executed this may consume considerable resources on a Skalli instance. You may want to schedule such actions during night times and choose an appropriate <minSeverity>.

VALIDATE_ALL

validates all entities of all types. The validation is done synchronously.

The specified <minSeverity> is passed to all registered validators, so that each validator can decide, whether it should produce issues or not. For example, a validator that checks links to other websites could be designed to produce FATAL issues, if the URL of the link is not a valid URL, ERROR issues, if the link points to a non-existing host, WARNING issues, if the host is temporarily unavailable, and finally INFO issues, if the link is redirected permanently and a project committer should adapt the link.

The severity of issues is defined as follows:

FATAL

The project (or one of its extensions) cannot be persisted before the issue is resolved. This severity usually indicates a syntactical problem, e.g. a malformed URL. Therefore, it makes not much sense to run a scheduled validation with <minSeverity> FATAL because such validations operate on persisted project data.

ERROR

The issue is serious but the entity can still be persisted. Example: A given URL is valid but points to a non-existing host.

WARNING

The issue is not serious, but should be fixed.

INFO

Not an issue at all, but a hint how the data quality of an entity could be improved further.

Scheduling the Maven POM Resolver

Skalli is able to extract information about the project coordinates and modules from the POM descriptors of Maven projects. Currently this mechanism is limited to projects for which sources are accessible through a gitweb frontend for a git repository. (TODO: describe the extension point for other MavenPathResolvers).

A project that wants to participate in that mechanism must enable the Maven project extension in the edit dialog and provide the path to its reactor POM. If the reactor POM resides in the project's root directory, the corresponding attribute can be left empty in the form.

Furthermore, you must configure a schedule for the asynchronous evaluation of the POM descriptors similiar to the scheduling of validation jobs above:

PUT https://<your-host>/api/config/ext/maven/resolver

<mavenResolver>
  <schedule>
    <daysOfWeek>*</daysOfWeek>
    <hours>*/2</hours>
    <minutes>0</minutes>
  </schedule>
  <userId>homer</userId>
</mavenResolver>

The example schedules the evaluation of all Maven reactor POMs on a daily basis every second hour (e.g. a 0:00, 2:00, ...). The entries of <schedule> support the usual crontab notation. Note that you must provide a suitable SCM loaction mapping to your gitweb instance (purpose: browse), e.g. something like

  <scmMapping>
    <id>browse.gitweb.example.org</id>
    <purpose>browse</purpose>
    <pattern>^scm:git:git://(git\.example\.org(:\d+)?)/(.*\.git)$</pattern>
    <template>http://{1}:50000/git/?p={3}</template>
    <name>Browse Sources in GitWeb</name>
    <provider>git</provider>
  </scmMapping>

The Maven resolver tries to match the SCM locations of a Maven project (i.e. of a project that has a Maven extension enabled) with the pattern specified in the mappping. If there is a matching, the reactor POM of the project is downloaded and evaluated recursively for modules. The result is stored in the Maven extension and displayed in the corresponding Maven info box.

Nexus Connector

If a Nexus connection is configured the Maven resolver described in the last section can determine available artifact versions for Maven projects:

GET https://<host>:<port>/api/config/ext/nexus

<nexus>
    <url>http://skalli.example.org/nexus/</url>
    <domain>repositories</domain>
    <target>build.milestones</target>
</nexus>

The Nexus connector uses the /service/local/data_index/<domain>/<target>/content?g=<groupId>&a=<artifactId> API call provided by Nexus (for details see https://repository.sonatype.org/nexus-indexer-lucene-plugin/default/docs/rest.data_index.html).

The retrieved artifact versions are stored in the Maven extension of a project.

News and Alerts

Defining the target for the What's New? link, as well as alert and info messages.

PUT https://<your-host>/api/config/view/news

<news>
  <url>http://host.examle.org/whatsnew/technology.skalli</url>
  <alert>This is a test system!</alert>
  <info>Next Planned Maintenance: tonight 10pm</info>
</news>

Notes:

Users are directed to the news URL when clicking on the version link in the upper right corner, too.
The alert message is rendered in a red box, while the info message is rendered in a light blue box. The latter can be used for example to announce a planned downtime. Both messages are positioned below the tag cloud on the Skalli home page.

Branding

Branding of Skalli by overwriting the default page title.

PUT https://<your-host>/api/config/view/branding

<branding>
  <pageTitle>Projects@Eclipse</pageTitle>
</branding>

Notes:

The default page title, if not otherwise configured, is Skalli.
The string maintained in <pageTitle> defines the second part of the page titles only. Depending on the page displayed the left part of the page title gives additional information about the page content. For example, the detail page of a project shows the name of the project in the page title.

Feedback Link

Providing a link to which users can send bug reports, feature requests, questions etc.

PUT https://<your-host>/api/config/view/feedback

<feedback>
  <url>mailto:skalli-support%40.example.org%3fsubject%3dFeedback</url>
  <displayName>Feedback</displayName>
</feedback>

Notes:

The maintained <url> is called when a user clicks on the feedback link displayed in the header of all Skalli pages (between the logged in user and the version information). Usually this link redirects to an email address (as in the example).
The string maintained in <displayName> is used as label for the feedback link.

Gerrit Connector

Configuring host/port and credentials for connections to a Gerrit server:

PUT https://<your-host>/api/config/gerrit

<gerrit>
   <host>host.example.org</host>
   <port>29418</port>
   <user>Arthur</user>
   <privateKey>-----BEGIN RSA PRIVATE KEY-----
      Proc-Type: 4,ENCRYPTED
      DEK-Info: DES-EDE3-CBC,61D359AC0BC0C4BD
 
      rSy...
   </privateKey>
   <passphrase>password</passphrase>
   <parent>parentProject</parent>
   <contact>mailto:gerrit-admins@example.corp</contact>
</gerrit>

Notes:

Use <contact> to specify a link to reach out for help with respect to the Gerrit server. A link, labeled Gerrit Contacts, will then appear on the Create Git/Gerrit Repository form. If empty no link will be rendered.
The <parent> property allows to set the name of a Gerrit project, that will be used as a parent for all projects created with the Create Git/Gerrit Repository form. Technically, this means that the newly created project will inherit the access rights from this parent project, allowing to provide some nice defaults.

REST API Usage

All information associated with a project and its extensions, issues, users, access statistics etc. can be retrieved from a REST-like API with HTTP GET commands. Write access currently is only partly implemented.

In general, the REST API uses the same URL scheme as the browsable UI. For example, the detail page of a project with name technology.skalli is accessible with the URL

https://<host>:<port>/projects/technology.skalli

The corresponding REST information then can be obtained with a GET request like

GET https://<host>:<port>/api/projects/technology.skalli

Note the prefix /api/ at the beginning of the resource path.

XML Schemas for the REST API

Skalli's REST API provides all resources as XML documents. XML schemas for these documents can be downloaded from a running Skalli instance with

GET https://<host>:<port>/schemas/<schema>

where <schema> is one of the following:

project.xsd: Schema for a single project resource
projects.xsd: Schema for the all projects list
subprojects.xsd: Schema for the subprojects list of a project
user.xsd: Schema for a user resource
issues.xsd: Schema for validation issues reported for a project
common.xsd: Common declarations used by all schemas

These schemas are documented and should be self-explaining.

Extensions provide their own XML schemas, for example:

extension-info.xsd: Schema for the Info extension (basic stuff like link to home page, mailing lists etc.)
extension-people.xsd: Schema for the People extension (info about project leads and committers)
extension-devinf.xsd: Schema for the Develoment Infrastructure extension (info about SCM locations, bugtracker etc.)
extension-scrum.xsd: Schema for the Scrum extension (additional info for projects following a Scrum-like development process)
extension-maven.xsd: Schema for the Maven extension (additional info for projects built with Maven)
extension-review.xsd: Schema for the Review extension (reviews and ratings of a project)

Note, this list is not complete since Skalli supports custom extensions. It is not required, but strongly encouraged that custom extensions provide a suitable XML schema, too. Skalli searches bundles implementing custom extensions for a folder named schemas and makes schemas found there available for download automatically (compare for example the bundle org.eclipse.skalli.model.ext.misc). The naming convention for schema files is extension-<shortname>.xsd. For details consult the tutorials and documentation about writing custom extensions.

Common REST Requests

List All Projects

To collect information about all the projects available in Skalli issue a GET request to /api/projects.

GET https://<host>:<port>/api/projects

The response looks similar to:

<?xml version="1.0" encoding="UTF-8" ?>
<projects xmlns="http://www.eclipse.org/skalli/2010/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API http://skalli.example.org/schemas/projects.xsd" 
    apiVersion="1.4">
  <project apiVersion="1.4" lastModified="2011-05-11T15:03:48.254Z" modifiedBy="admin">
    <uuid>98620072-2e54-4e71-9ce1-51a81fc8761c</uuid>
    <id>hello</id>
    <template>default</template>
    <name>Hello World</name>
    <link rel="project" href="http://skalli.example.org/api/projects/98620072-2e54-4e71-9ce1-51a81fc8761c"/>
    <link rel="browse" href="http://skalli.example.org/projects/hello"/>
    <link rel="issues" href="http://skalli.example.org/api/projects/98620072-2e54-4e71-9ce1-51a81fc8761c/issues"/>
    <phase>initial</phase>
    <description>The Hello World projects is a default dummy project</description>
    <extensions/>
  </project>
  <project>...</project>
 </projects>

Note that by default only some basic information is returned for each project, but no information from the project's extensions. However, by adding the query parameter extensions=<comma-separated list of extensions> to the URL, you can choose to retrieve information from selected extensions, too.

For example, with

https://<host>:<port>/api/projects?extensions=people,devInf

you could obtain the project leads and committers of all projects as well as information about the development resources (repositories, bugtrackers etc.) used by these projects.

The XML schema for the response can be retrieved from any running Skalli instance with the URL https://<host>:<port>/schemas/projects.xsd.

Search Projects

The REST API supports searching for projects with Lucene queries. Furthermore, you can retrieve all projects with a certain tag.

Searching with a Lucene query:

https://<host>:<port>/api/projects?query=<lucene query string>

Searching for all projects with a certain tag:

https://<host>:<port>/api/projects?tag=<tag>

The result is a list of projects with the same level of details as for the "all projects list" above, i.e. by default no information from project extensions is returned. However, by adding the query parameter extensions=<comma-separated list of extensions> to the URL, you can choose to retrieve information from selected extensions, too.

If not otherwise specified, the requests return all matching results sorted by relevance, best matches first. If you want to limit the number of hits returned by the query, add the query parameter count=<number of hits> to the request URL. You can also consume the result "page by page" like in the UI by adding the query parameter start=<index of first hit> to the request URI.

Project Details

In order to retrieve detail information about a certain project and its extensions, use a REST call of the following pattern:

GET https://<host>:<port>/api/projects/<projectId>

You can either use the project's symbolic name, e.g. technology.skalli, or its UUID. Note that the symbolic name of a project can change over time, while the UUID is fixed once the project is created.

A typical result would look like this:

<?xml version="1.0" encoding="UTF-8" ?>
<project xmlns="http://www.eclipse.org/skalli/2010/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API https://skalli.example.org/schemas/project.xsd" 
    apiVersion="1.4" lastModified="2011-11-21T10:42:44.176Z" modifiedBy="hugo">
  <uuid>2f50f2a1-ddaf-4e7b-adea-e10294303887</uuid>
  <id>technology.skalli</id>
  <template>default</template>
  <name>Eclipse Skalli</name>
  <shortName>skalli</shortName>
  <link rel="project" href="https://skalli.example.org/api/projects/2f50f2a1-ddaf-4e7b-adea-e10294303887"/>
  <link rel="browse" href="https://skalli.example.org/projects/technology.skalli"/>
  <link rel="issues" href="https://skalli.example.org/api/projects/2f50f2a1-ddaf-4e7b-adea-e10294303887/issues"/>
  <phase>Incubation</phase>
  <description>One of the major goals of this project is to make a new generation project management 
tool accessible and usable by the Eclipse community and other open source projects.... </description>
  <link rel="parent" href="https://skalli.example.org/api/projects/5856b08a-0f85-4d31-b007-ab367cfd247a"/>
  <members>
    <member>
      <userId>mochmann</userId>
      <link rel="user" href="https://skalli.example.org/api/user/mochmann"/>
      <role>projectmember</role>
    </member>
    <member>
      <userId>bvariwg</userId>
      <link rel="user" href="https://skalli.example.org/api/user/bvariwg"/>
      <role>projectmember</role>
    </member>
    <member>
      <userId>skaufmann</userId>
      <link rel="user" href="https://skalli.example.org/api/user/skaufmann"/>
      <role>projectmember</role>
      <role>projectlead</role>
    </member>
  </members>
  <extensions>
    <devInf xmlns="http://www.eclipse.org/skalli/2010/API/Extension-DevInf" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API/Extension-DevInf https://skalli.example.org/schemas/extension-devinf.xsd"
        apiVersion="1.0" lastModified="2011-09-30T17:43:43.425Z" modifiedBy="mochmann" inherited="false" derived="false">
      <bugtrackerUrl>https://bugs.eclipse.org/bugs/buglist.cgi?query_format=specific&amp;order=relevance+desc&amp;bug_status=__open__&
amp;product=Skalli</bugtrackerUrl>
      <ciUrl>https://hudson.eclipse.org/hudson/job/skalli/</ciUrl>
      <scmLocations>
        <scmLocation>scm:git:git://git.eclipse.org/gitroot/skalli/org.eclipse.skalli.git</scmLocation>
      </scmLocations>
    </devInf>
    <info xmlns="http://www.eclipse.org/skalli/2010/API/Extension-Info" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API/Extension-Info https://skalli.example.org/schemas/extension-info.xsd"
          apiVersion="1.0" inherited="false" derived="false">
      <homepage>http://www.eclipse.org/skalli/</homepage>
      <mailingLists>
        <mailingList>skalli-dev@eclipse.org</mailingList>
      </mailingLists>
    </info>
    <people xmlns="http://www.eclipse.org/skalli/2010/API/Extension-People" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API/Extension-People https://skalli.example.org/schemas/extension-people.xsd" 
          apiVersion="1.0" inherited="false" derived="false">
      <leads>
        <lead>
          <userId>skaufmann</userId>
          <link rel="user" href="https://skalli.example.org/api/user/skaufmann"/>
        </lead>
      </leads>
      <members>
        <member>
          <userId>mochmann</userId>
          <link rel="user" href="https://skalli.example.org/api/user/mochmann"/>
        </member>
        <member>
          <userId>bvarwig</userId>
          <link rel="user" href="https://skalli.example.org/api/user/bvarwig"/>
        </member>
        <member>
          <userId>rwetzold</userId>
          <link rel="user" href="https://skalli.example.org/api/user/rwetzold"/>
        </member>
      </members>
    </people>
    ...
  </extensions>
</project>

The XML schema for the response can be retrieved from any running Skalli instance with the URL https://<host>:<port>/schemas/project.xsd.

It is also possible to retrieve known validation issues for a certain project:

GET https://<host>:<port>/api/projects/<projectId>/issues

The response could look like the following:

<issues 
        xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API https://skalli.example.org/schemas/issues.xsd" 
        apiVersion="1.0" lastModified="2011-11-30T05:42:19.722Z" modifiedBy="skalli">
    <isStale>false</isStale>
    <issue>
        <timestamp>1322631739713</timestamp>
        <severity>WARNING</severity>
        <extension>org.eclipse.skalli.model.core.Project</extension>
        <propertyId>description</propertyId>
        <issuer>org.eclipse.skalli.common.util.ProjectDescriptionValidator</issuer>
        <item>0</item>
        <message>The project description is empty. Let others know what this is about.</message>
    </issue>
    <issue>
        <timestamp>1322631739713</timestamp>
        <severity>WARNING</severity>
        <extension>org.eclipse.skalli.model.ext.devinf.DevInfProjectExt</extension>
        <propertyId>ciUrl</propertyId>
        <issuer>org.eclipse.skalli.common.util.HostReachableValidator</issuer>
        <item>0</item>
        <message>'https://hudson.eclipse.org/hudson/job/skali/' not found on target server (404 Not Found).</message>
    </issue>
</issues>

In the example, the project has two validation issues, both of severity WARNING, one in the project's basic information (the description is missing), and another in the Development Infrastructure extension (the URL has a typo and therefore points to nowhere). The lastModified attribute tells when the project has been checked last, and the <isStale> tag indicates whether the following list of issues is still valid. Since Skalli executes all validation checks asynchronously, it might happen that the project is already scheduled to be re-validated in the near future. In that case, the stale flag is set and a client may decide to wait for the re-validation, or take the (possibly outdated) result from the last run.

The XML schema for the response can be retrieved from any running Skalli instance with the URL https://<host>:<port>/schemas/issues.xsd.

List of Subprojects

To list all subprojects for a given project use the following request:

GET https://<host>:<port>/api/projects/<projectId>/subprojects

The response returns a plain unsorted list of subprojects. It is possible to provide a depth of search as a request parameter:

GET https://<host>:<port>/api/projects/<projectId>/subprojects?depth=<depth>

If depth is not specified, the search will traverse the whole project hierarchy.

A typcial example of a project with some subprojects could look like the following:

<?xml version="1.0" encoding="UTF-8" ?>
<subprojects xmlns="http://www.eclipse.org/skalli/2010/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API https://skalli.example.org/schemas/subprojects.xsd" 
     apiVersion="1.0">
  <project apiVersion="1.4" lastModified="2011-11-21T10:42:44.176Z" modifiedBy="hugo">
    <uuid>2c50f6a1-ddaf-4e7b-aded-e10295303887</uuid>
    <id>technology.skalli</id>
    <template>default</template>
    <name>Eclipse Skalli Orbit</name>
    <shortName>skalliorbit</shortName>
    <link rel="project" href="https://skalli.example.org/api/projects/2c50f6a1-ddaf-4e7b-aded-e10295303887"/>
    <link rel="browse" href="https://skalli.example.org/projects/technology.skalli"/>
    <link rel="issues" href="https://skalli.example.org/api/projects/2c50f6a1-ddaf-4e7b-aded-e10295303887/issues"/>
    <phase>Incubation</phase>
    <description>...</description>
    <link rel="parent" href="https://skalli.example.org/api/projects/5856b08a-0f87-4d91-b007-ac367ced247a"/>
    <extensions/>
  </project>
  <project apiVersion="1.4" lastModified="2011-09-12T12:40:09.877Z" modifiedBy="hugo">
      ...
  </project>
</subprojects>

The content is the same as for the list of all projects above and contains no information from project extensions by default. However, by adding the query parameter extensions=<comma-separated list of extensions> to the URL, you can choose to retrieve information from selected extensions, too.

The XML schema for the response can be retrieved from any running Skalli instance with the URL https://<host>:<port>/subprojects.xsd.

User Information

To get the contact information of a certain user use the following REST request:

GET https://<host>:<port>/api/user/<userId>

The response will look similar to:

<?xml version="1.0" encoding="UTF-8" ?> 
<user xmlns="http://www.eclipse.org/skalli/2010/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API http://skalli.example.org/schemas/user.xsd" apiVersion="1.0">
  <link rel="self" href="https://skalli.example.org/api/user/mochmann" /> 
  <userId>mochmann</userId> 
  <firstname>Michael</firstname> 
  <lastname>Ochmann</lastname> 
  <email>...</email> 
  <phone>...</phone> 
  <sip>...</sip> 
  <company>...</company> 
  <department>...</department> 
  <location>...</location> 
  <room>...</room> 
</user>

The XML schema for the response can be retrieved from any running Skalli instance with the URL https://<host>:<port>/schemas/user.xsd.

Admin Tasks

List of Bundles

To get the statuses for all referenced bundles issue a GET request to /api/admin/status

GET https://<host>:<port>/api/admin/status

The response will contain a list of bundles:

<bundles>
 <bundle>
      <name>org.eclipse.skalli.common</name>
      <version>0.1.0.qualifier</version>
      <state>Active</state>
    </bundle>
  <bundle>...</bundle>
 </bundles>

with their names, versions and states (ACTIVE, INSTALLED, UNINSTALLED, STARTING, STOPPING, RESOLVED)

Statistics

To see the information about the usage of your application issue a GET request to /api/admin/statistics

GET https://<host>:<port>/api/admin/statistics

The response provides you with statistics from the last start of the application and contains such info as the amount of users, their IDs, locations, which browsers and URLs they used, which search strings, etc.:

<?xml version="1.0" encoding="UTF-8" ?>
<statistics xmlns="http://www.eclipse.org/skalli/2010/API/Admin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.eclipse.org/skalli/2010/API/Admin 
     http://skalli.example.org/schemas/admin-statistics.xsd" apiVersion="1.0">
  <info>
    <started>01.06.2011 16:07:02</started>
    <snapshot>03.06.2011 16:34:47</snapshot>
    <duration>02 days 00:27:45</duration>
  </info>
  <users>
    <count>0</count>
    <userIds/>
    <locations/>
    <departments/>
  </users>
  <browsers/>
  <referers>
    <referer count="12">admin</referer>
  </referers>
  <usages/>
  <searches/>
</statistics>

Backup Resources

To backup the project data use the following request:

GET https://<host>:<port>/api/admin/backup

This returns a ZIP file containing the storage folder.

Monitor the Validation Queue

To get the status and content of currently queued items in the validation queue use a REST request of the following form:

GET https://<host>:<port>/api/admin/services/org.eclipse.skalli.core.validation/monitors/queue

Note, you might register custom monitors for other services, too. (TODO: describe the service monitor extension point).

Terms

[Skalli] Extension	All display & application logic elements needed to provide a specific functionality. You can write your own extensions and bring Skalli to visualise their information.
Info Box	A single box displaying the information of one extension to the user
Project Details Page	The main project page containing the info boxes
View Mode	The project details page without edit forms and without initially visible editing capabilities
Navigation Panel	The list of links on the left hand side (currently of the project details page)
Edit Mode	The forms page when clicking edit in the navigation panel of the project details page

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Skalli/User Guide

Contents

Getting Started

Option 1: Out-Of-the-Box

Option 2: Installing Jetty Web RT

Option 3: Deploying Skalli with P2

Tutorials

How to Implement Skalli Extensions

Configuration

Choosing the Storage Service

Using File System Based Storage: Setting the Working Directory

Configuring LDAP

Switching between LDAP and a Local User Store

Configuring Administrator Users

User Details Links

Proxy

Automatic URL Inference from SCM Location

Mappings for Eclipse Projects

Automatic URL Inference from Mailing Lists

Mappings for Eclipse Projects

Scheduling of Validation Jobs

Scheduling the Maven POM Resolver

Nexus Connector

News and Alerts

Branding

Top Links

Feedback Link

Gerrit Connector

REST API Usage

XML Schemas for the REST API

Common REST Requests

List All Projects

Search Projects

Project Details

List of Subprojects

User Information

Admin Tasks

List of Bundles

Statistics

Backup Resources

Monitor the Validation Queue

Terms