Skalli/User Guide

Tutorials

How to Implement Skalli Extensions

You can write your own extension. A Skalli extension are all display & application logic elements needed to provide a specific functionality. You can simply bring Skalli to visualise their information.

Find out how to write your extension:

• Five Minutes Tutorial
• Extended Tutorial

Configuration

There are different configuration possibilities for Skalli.

Various configuration settings can be managed via REST API calls. (There is a good Firefox add-in for that: RESTClient)

If you do not know how to obtain the Skalli sources and how to start it, please visit Contributor Guide first.

The Workdir

The working directory of Skalli is the place where all data is stored.

In the subdirectory storage Skalli persists information about projects, favorites, issues, users etc. Customization settings are stored in the subdirectory customization.

The workdir can be specified

1. by defining a property workdir in the configuration file /skalli.properties (value is the absolute path of the working directory)
2. by defining the system property workdir=<path-to-working-directory>

If workdir is not set explicitly the current directory is used as default.

Using the Local User Store

Skalli is able to use LDAP for user management. If you want to use a local user store instead the LDAP user service in Skalli has to be disabled.

Open the OSGi console and type ls. Search for a service with the name org.eclipse.skalli.core.user.ldap and stop it (disable <ID>). Search for the service with name org.eclipse.skalli.core.user.local and start it (enable <ID>).

Users are stored in the directory <workdir>/storage/User. 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>

Note that 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.

Configuring Administrator Users

Skalli administrators are allowed to do more than normal users, eg. 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.

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 PUT 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>

Note, Skalli administrator rights are necessary to perform that request.

Automatic URL Inference from SCM Location

A Skalli project can enable the "Development Infrastruture" extension to provide information about the project's source code repository, continous integration build (e.g. on a Hudson/Jenkins server), bug tracker used to track issues etc. Additionally, a link to a browsable frontend 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 [1].

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 frontend of an SCM system like gitweb), review (for a link to a code review system like Gerrit) and activity (for a link to information about the commit activity of a project). However, Skalli Extentions 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.

REST API Usage

Admin Tasks

List of Bundles

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

GET https://<your-host>/api/admin/status

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 collect the information about the usage of your application issue a GET request to /api/admin/statistics

GET https://<your-host>/api/admin/statistics

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://localhost:8080/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>

Common Tasks

List the Projects

To collect the information about all the projects available in Skalli issue a GET request to /api/projects. As a prerequisite you must be logged into Skalli and provide your login ID within the request:

GET https://<your-host>/api/projects?referrer=<userId>

And 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://localhost:8080/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://<your-host>/api/projects/98620072-2e54-4e71-9ce1-51a81fc8761c"/>
    <link rel="browse" href="http://<your-host>/projects/hello"/>
    <link rel="issues" href="http://<your-host>/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>

Project Details

Previous request returned info on all the projects. You might want to limit this to only one project. To do so provide projects ID in the request:

GET https://<your-host>/api/projects/<projectId>?referrer=<userId>

It is also possible to list the issues for a specific project:

GET https://<your-host>/api/projects/<projectId>/issues?referrer=<userId>

Response will return known validation problems in the xml form.

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