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.feature/rootfiles/storage to your storage folder as a start.

Tutorials

If you want to try out the following walktrough yourself, download and start an instance of Skalli as explained above. Login as user ad with password milliways. If the login screen is not directly visible after starting Skalli, click on the link titled (Login) in the upper right corner of the Skalli homepage.

Note, if you are behind a firewall you should configure a proxy first.

Skalli in 20 Minutes: A Quick Walkthrough

First of all, to correct a common misunderstanding just from the beginning, Skalli is not another software hosting facility like Sourceforge, GitHub or GoogleCode. It provides no source code repository, no build system, not even a Wiki or another document storage facility. So what is Skalli about?

Large software development organizations, including but not limited to large software companies and open source foundries like Eclipse, typically struggle with an ever growing amount of projects to deal with. Usually these projects have grown in a quite heterogenous environment with respect to the development tools and infrastructure used. For example, some older projects may host their source code still in CVS or Subversion source code repositories, while new development may happen in Git. Some projects may be built with ANT, while others rely on Maven. Documentation may be partly stored in a central Wiki, but some teams may prefer to store their documents simply on a file share. That is a common observation: One size does (usually) not fit all, and developers are especially insistent with respect to their liked — or more worse: disliked — development tools. Still, organizations strieve to get and retain an overview of all the projects in such a heterogenous environment — and surprisingly often fail.

Skalli tries to fill that gap. It links the various bits and pieces of a project together, gathers information about the projects in an organization, makes this information searchable — and in the consequence: manageable. In doing so, Skalli stores only a very small amount of original data. Remember, Skalli is not another source code repository. Projects can host their source code in whatever source code repository that suits their needs best. Skalli just keeps links to all the repositories and may — currently only for Git — help new projects to initially create repositories, but the actual source code is stored somewhere else.

Knowing that, it should not be a big surprise that the start screen of Skalli looks like the following:

Skalli home page with search field, quick access links and tag cloud

Quite frugal, you might say, but looking a bit more closely, this screen expresses quite exactly the philosophy of Skalli: All is about searching and finding projects that might be important or interesting for you. Just type what you are searching for into the input field, e.g. type modeling, and click on the Search button.

Search result page with navigation links and a list projects matching a given query

This screenshot shows a typcial result of a search query. The project that matches your search query best is displayed on top of the result list. Navigate through the result list with the links at the bottom of the page or choose how many results Skalli should display per page with the links provided above the result list. The overall amount of search hits is displayed beneath the search field in header bar.

Each entry of a query result page provides the most important information about a project in condensed form.

Details provided for a search hit: Title, synopsis, links to important resources, tags and information about the project's position in the project hierarchy

Besides the title of the project and a short synopsis of what the project is about you see a line with some links to important project resources — like the project's home page — and another line with tags that members of the project or just other interested parties have assigned to the project. You can assign arbitrary tags to any project, even if you are not a member of that project.

Note the title of the project entry: It is a link that navigates you to another page with all the project's details:

Detailed information about a project, for example about the development resources, mailing lists, committers and related projects

Each panel — or info box how we prefer to call them — on this page provides a certain piece of information about the project. Some of these boxes are common to almost all projects, e.g. the About and Team boxes. Others can be switched off if the project has no need for them. You can even implement custom info boxes for your instance of Skalli!

We don't want to explain all available info boxes here in detail, but just mention a few of them that you might most certainly want to add to your project:

About: This info box in the left column shows the description of the project, tags assigned to it, a link to the project's homepage and the current state of the project (Mature in the example).
Mailing Lists: This info box in the left column provides mailing lists that you can use to communicate with the project members. Clicking on the mailing list link (e.g. emf-dev@eclipse.org in the example) opens a mail client. The links for subscribing/unsubscribing and browsing are automatically generated if you provide a suitable mapping configuration.
Development Infrastructure: This info box in the left column groups the most important information for developers of the project, e.g. links to the source code repository, build system and bug tracker. Some of the links are generated automatically by the info box if you provide suitable mapping configurations.
Additional Links: This info box in the left column let's you manage additional links for a project. Links can be grouped under common captions.
Project Hierarchy: This info box in the right column shows the position of the project in the project hierarchy and allows and easy navigation to the project's parent and sub projects.
Team: This info box in the right column lists the team leads and committers associated with the project. If a suitable mapping is provided, the name entries are rendered as links leading to an address book or something similar where more information about the project members can be retrieved. Furthermore, by clicking on the projects link right to the name of a committer, you get a list of other projects this committer is associcated with.
Related Projects: This info box in the right column displays projects that are somehow similiar to the displayed one and you might likely be interested in visiting them, too.
Issues: This box in the right column is only visible to project members and shows issues Skalli has found when validating the project. Skalli checks the information maintained by a project periodically and gives hints how the data quality could be improved. In the example, Skalli has detected that the homepage link points to nowhere and should be corrected.

Let's assume you want to correct the typo in the homepage link now. If you are a project member — and Arthur Dent, the guy you have logged in as, happens to be member of the Eclipse Modeling Framework (EMF) project — you should see an Edit link in the left navigation bar (in the section This Project). Clicking it navigates you to the following page:

Edit page of the project Eclipse Modeling Framework (EMF). Each section can be switched on or off independently

The screenshot shows only the upper part of the edit page — scroll down to see what else you can maintain — but the point of interest, the invalid homepage link, is clearly marked by Skalli. The correct URL is http://www.eclipse.org/modeling/emf/. Change that and press the Check button at the top of the page. This will revalidate the project and the red error markers should vanish.

Let's have a closer look at what else you can do on this screen: The edit page presents all available extensions you can assign to your project. Nearly every piece of information you can assign to a project comes in the form of an extension. In it's simplest form, a project has just a unique identifier (the Project ID), which is of are more technical nature, and a human readable name that appears as title of the project in the user interface. These are the only mandatory properties you must fill in upon creation of a project. Everything else can be provided later.

In order to assign an extension to a project, just click on the "edit" link in the title bar of the corresponding form. Scroll down to the form titled with Scrum and enable it. We want to assign a Product Owner for the EMF project: Click on Add User, search for art, select Arthur Dent from the search result and leave the search dialog with Add and Close. The form now should look like this:

Enabling the Scrum extension for a project that is dedicated to information related to an agile development method

Leave the edit dialog with the OK button at the bottom of the page. You should see a new info box with title Scrum in the right column of the project's detail page now:

Enabling the Scrum extension produced an additional info box on the project's detail page

Let's go back to the start page of Skalli — you can do that by clickling on the small Skalli logo that appears on all detail screens and most other Skalli pages in the upper left corner — and have a closer look at the links beneath the search input field.

Fast access links navigating to an all projects overview page, to the logged in user's projects and favorites, and to the screen for creating of new projects

The link titled All Projects navigates to an overview page showing all projects known to Skalli in their respective places in the project hierarchy. This has not been mentioned yet, but projects can have an arbitrary amount of subprojects, and each project can have a parent project (one and only one, or none if it is a top-level project). A typical project hierarchy may look like this:

Hierarchical view of all registered projects

Projects in this view are sorted alphanumerically with the top-level projects in bold letters, while subprojects are printed with indentation and in smaller font. You may expand and collapse the individual nodes of the project hierarchy with the corresponding links to gain a better overview, or drill down into parts of the hierarchy with the browse link.

Follwing the link titled My Projects on the Skalli homepage is equivalent to a search for all projects to which the currently logged in user, Arthur Dent, is assigned to either as project lead or committer. The result is presented in the condensed search hit format similar to what has been shown above for the search query modeling. Furthermore, a logged in user like Arthur Dent can mark arbitrary projects as his favorites. You might have recognized the little light bulbs on the project's detail page or on the search result page next to the project titles and wondered whether that is just decoration? Nothing of that kind!

Adding a project to your favorite projects

By simply clicking the icon you can add a project to your favorite projects. The little light bulb icon then changes its color from grey to yellow. Of course, you can remove the project from your favorite projects the same way. To see your favorites, click on the My Favorites in the left navigation pane, or on the Skalli homepage.

Let's finally see how you can create a new project: On the Skalli homepage you will find the link Create Project that navigates you to a page where you can choose what kind of project to create:

Selecting the type of a new project

Currently Skalli provides only two types of projects, free-style projects and free-style components, but you can add custom project types quite easily. The distinction between projects and components is not so sharp as it might appear, but the general idea is the following: In Skalli's philosophy projects are about people — just a couple of people come together to share an idea, work together or produce something, which is not necessarily software. On the other side, there are quite often certain more technically oriented aspects of a project, project artifacts or processes of some kind, and for that Skalli provides components. In practise you will see components usually in deeper levels of a project hierarchy, and actually the only hard rule Skalli forces upon components is that a component must never be the parent of a project.

Let's not bother you with these details now, but just accept the default and click on Create Project. The next screen however should be quite familiar to you: It is just the edit page we have seen before. The only difference is that all the forms are empty and most of the extensions are initially switched off. As mentioned above, Skalli is not very demanding with respect to the minimal set of properties you must maintain for a project: Just enter a Project Id, which must be unique among all the projects so that it can, for example, be used as part of the URL of the project's detail page, and a human readable name that will appear as title of the project everywhere. That's it! Just press OK and admire the project page Skalli creates for you.

This concludes our little walkthrough of the basic screens of Skalli. However, there is much more to discover!

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.

Hint: currently for the feedExtention now File Based Storage Service implemented. If you want to use feeds, you have to use a DB Based Storage!

Using a DB Based Storage

If you are using the DB based storage mechanism, you have to set the property skalli.storageService to org.eclipse.skalli.storage.db.PersistenceDB.

By default a clean in-memory Derby database is used. You can configure your own database by setting properties.

Skalli contains two persistence units: store and feed. It is possible to choose different configurations for each persistence unit. You can configure all public static final fields from org.eclipse.persistence.config.PersistenceUnitProperties.

Property Format: skalli.persistence.[PersistenceUnit].PersistencePropertyValue=YourValue.

Example properties for a Derby database in the current workdir:

-Dskalli.storageService=org.eclipse.skalli.storage.db.PersistenceDB
 
-Dskalli.persistence.eclipselink.target-database=Derby
-Dskalli.persistence.javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
-Dskalli.persistence.javax.persistence.jdbc.url=jdbc:derby:SkalliDB;create=true
-Dskalli.persistence.javax.persistence.jdbc.user=skalli
-Dskalli.persistence.javax.persistence.jdbc.password=skalli

Example properties for using two different Derby databases in C:/tmp:

-Dskalli.storageService=org.eclipse.skalli.storage.db.PersistenceDB
 
-Dskalli.persistence.eclipselink.target-database=Derby
-Dskalli.persistence.javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
-Dskalli.persistence.store.javax.persistence.jdbc.url=jdbc:derby:C:/tmp/SkalliStoreDB;create=true
-Dskalli.persistence.feed.javax.persistence.jdbc.url=jdbc:derby:C:/tmp/SkalliFeedDB;create=true
-Dskalli.persistence.javax.persistence.jdbc.user=skalli
-Dskalli.persistence.javax.persistence.jdbc.password=skalli

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. Skalli for example has a mechanism for checking of URLs defined by projects, and for that it needs to be able to communicate with the outside world. You can define the proxy to use by starting the Java virtual machine with the usual system properties http.proxyHost, http.proxyPort and proxy.nonProxyHosts.

Example:

-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080 -Dproxy.nonProxyHosts="*.example.org;*.example.com;non-proxy-host"

Alternatively you may configure the proxy with a REST call 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

copy-to-clipboard

for a link that is to be copied to the clipboard. This mapping can for example be used to convert an scm location of the form scm:git:git://git.example.org/skalli.git to https://myaccount@git.example.org/skalli.git prior to copying it to the clipboard. For that, the mapping supports the additional variable ${userId}.
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 caption an info box should render for mapped links.
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>clipboard.git.eclipse.org</id>
    <purpose>copy-to-clipboard</purpose>
    <pattern>^scm:git:git://git.eclipse.org/gitroot/(.+\.git)$</pattern>
    <template>https://${userId}@git.eclipse.org/gitroot/${1}</template>
    <name>Copy SCM Location to Clipboard</name>
    <provider>git</provider>
  </scmMapping>
  <scmMapping>
    <id>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.

Destination Service

Skalli extensions can access external systems to gather information, e.g. the Maven & Nexus Resolver or Feeds. Access to such systems can be restricted and credentials are needed (e.g. with https). The destination service allows to store such credentials and provides a pre-configured http client to the extension. It will try to match all supplied regular expression destination patterns with the supplied URL and if a match is found, configure the credentials. Currently BASIC authentication is supported.

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

<destinations>
  <destination>
    <id>gitweb.basic-auth</id>
    <authenticationMethod>basic</authenticationMethod>
    <pattern>^https://(git\.example\.org):50001/git/(.*)$</pattern>
    <user>skalli</user>
    <password>verysecretpassword</password>
  </destination>
</destinations>

In a GET request the password will be omitted due to security reasons.

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).

Mass Data Change

It might be handy to change a certain property in all the projects, that contain it. To list all the projects that would be affected by this change use:

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

Where Lucene query is: *&property=<extension.propertyName>&pattern=<reg.expression> If property is given in a form property=propertyName, it is assumed to be a Project property.

Use URl-encoder to encode the pattern, e.g. http://www.dorf-rauxel.de/picard/tools/urlcode.php

Result should return a list of projects, matching the search query, i.e. projects with the given extension where a given property matches a given pattern.

To replace the value of the property:

PUT https://<host>:<port>/api/projects?query=<lucene query string>&persist=true

Where body should contain a template for the replacement:

<dataChangePattern>
   <template>regex</template>  
</dataChangePattern>

If persist flag is not set to true, the operation would only verify the data and report an error if validation fails.

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

Skalli in 20 Minutes: A Quick Walkthrough

How to Implement Skalli Extensions

Configuration

Choosing the Storage Service

Using File System Based Storage: Setting the Working Directory

Using a DB Based Storage

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

Destination Service

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

Mass Data Change

Terms