Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Skalli/User Guide"
m (we closely follow HTTP and stick to the misspelled 'referer') |
(Added some background info about REST API and schemas) |
||
Line 202: | Line 202: | ||
= REST API Usage = | = REST API Usage = | ||
+ | |||
+ | All information associated with a project and its extensions, issues, users, access statistics etc. can be retrieved from a [http://en.wikipedia.org/wiki/REST 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 | ||
+ | <source lang="text"> | ||
+ | https://<your-host>/projects/technology.skalli | ||
+ | </source> | ||
+ | |||
+ | The corresponding REST information then can be obtained with a GET request like | ||
+ | <source lang="text"> | ||
+ | GET https://<your-host>/projects/technology.skalli | ||
+ | Accept: text/xml | ||
+ | Referer: <contact information of the calling client, e.g. a user id or mail address> | ||
+ | </source> | ||
+ | |||
+ | The <code>Accept</code> header tells Skalli to return REST information as XML document instead of an HTML page. The <code>Referer</code> header is used by Skalli to track clients. Since the REST API is not yet finalized, the contact information provided in the header can be used to inform clients about changes in the API. | ||
+ | |||
+ | Alternatively, instead of sending HTTP headers, you can obtain the same with | ||
+ | <source lang="text"> | ||
+ | GET https://<your-host>/api/projects/technology.skalli?referer=<identifier> | ||
+ | </source> | ||
+ | |||
+ | Note the prefix <code>/api/</code> at the beginning of the resource path. | ||
+ | |||
+ | === XML Schemas for the REST API === | ||
+ | |||
+ | As stated above, the REST API provides all resources as XML documents. XML schemas for these documents can be downloaded from a running Skalli instance with | ||
+ | <source lang="text"> | ||
+ | GET https://<your-host>/schemas/<schema> | ||
+ | </source> | ||
+ | where <code><schema></code> is one of the following: | ||
+ | :; project.xsd : Schema for a single project resource | ||
+ | :; projects.xsd : Schema for the all projects list | ||
+ | :; 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 [http://en.wikipedia.org/wiki/Scrum_%28development%29 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 [http://wiki.eclipse.org/Skalli/User_Guide/Tutorial/Extensions/Extended_Tutorial tutorials] and documentation about writing custom extensions. | ||
== Common Tasks == | == Common Tasks == | ||
Line 226: | Line 273: | ||
<link rel="issues" href="http://<your-host>/api/projects/98620072-2e54-4e71-9ce1-51a81fc8761c/issues"/> | <link rel="issues" href="http://<your-host>/api/projects/98620072-2e54-4e71-9ce1-51a81fc8761c/issues"/> | ||
<phase>initial</phase> | <phase>initial</phase> | ||
− | <description>The Hello World projects is a default dummy project | + | <description>The Hello World projects is a default dummy project</description> |
<extensions/> | <extensions/> | ||
</project> | </project> | ||
Line 232: | Line 279: | ||
</projects> | </projects> | ||
</source> | </source> | ||
+ | |||
+ | 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 | ||
+ | <source lang="text"> | ||
+ | https://projectportal.wdf.sap.corp/api/projects?extensions=people,devInf&referer=d032916 | ||
+ | </source> | ||
+ | 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. | ||
=== Project Details === | === Project Details === |
Revision as of 09:32, 10 June 2011
Getting Started
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:
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
- by defining a property workdir in the configuration file /skalli.properties (value is the absolute path of the working directory)
- 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
- 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 bugtracking system
- 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.
- 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 pimarily 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=[^&]*).*</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&month=x&project={0}</template> <name>Commits by Company by Month</name> <provider>git</provider> </scmMapping> </scmMappings>
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://<your-host>/projects/technology.skalli
The corresponding REST information then can be obtained with a GET request like
GET https://<your-host>/projects/technology.skalli Accept: text/xml Referer: <contact information of the calling client, e.g. a user id or mail address>
The Accept
header tells Skalli to return REST information as XML document instead of an HTML page. The Referer
header is used by Skalli to track clients. Since the REST API is not yet finalized, the contact information provided in the header can be used to inform clients about changes in the API.
Alternatively, instead of sending HTTP headers, you can obtain the same with
GET https://<your-host>/api/projects/technology.skalli?referer=<identifier>
Note the prefix /api/
at the beginning of the resource path.
XML Schemas for the REST API
As stated above, the REST API provides all resources as XML documents. XML schemas for these documents can be downloaded from a running Skalli instance with
GET https://<your-host>/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
- 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 Tasks
List the Projects
To collect 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 user ID within the request:
GET https://<your-host>/api/projects?referer=<userId>
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>
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://projectportal.wdf.sap.corp/api/projects?extensions=people,devInf&referer=d032916
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.
Project Details
The previous request returned info on all the projects. You might want to limit this to only one project. To do so provide the project's ID in the request:
GET https://<your-host>/api/projects/<projectId>?referer=<userId>
It is also possible to list the issues for a specific project:
GET https://<your-host>/api/projects/<projectId>/issues?referer=<userId>
The response will return known validation problems in XML format.
User Info
To get the contact information of the user issue a GET request to api/user:
GET https://<your-host>/api/user/<userId>?referer=<userId>
As a prerequisite, you should be logged into Skalli and provide your user ID.
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://<your-host>/schemas/user.xsd" apiVersion="1.0"> <link rel="self" href="https://<your-host>/api/user/<userId>" /> <userId>...</userId> <firstname>...</firstname> <lastname>...</lastname> <email>...</email> <phone>...</phone> <sip>...</sip> <company>...</company> <department>...</department> <location>...</location> <room>...</room> </user>
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
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://<your-host>/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://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>
Backup Resources
To backup the project data use the following request:
GET https://<your-host>/api/admin/backup?referer=<userId>
This returns a ZIP file containing the storage folder.
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 |