In this basic guide I want to explain on a high level, what and where you can find the things you need for Development in the SDK of Polarion.
Although there is a lot of information in the SDK, it isn’t necessarily easy to find or self explaining. So I want to give a high-level overview of all the things, that you can find in the SDK. But how to use the APIs will be topic of other blog entries.
You can find the Polarion sdk on any Polarion instance under: [YourPolarionURL]/polarion/sdk/index.html.
The SDK is also available offline in your local Polarion folder: Polarion/polarion/SDK.
If you want to develop Java extensions, you will need the additional files of the offline SDK. There you can find the libraries and examples for Java extensions for Polarion.
Basically I will go trough each section of the SDK and give basic information about it:
- SDK Guides & Examples
- Polarion Open Java API („Open API“)
- Polarion Rendering API („Rendering API“)
- Polarion WebServices API
- Database
- Other Resources
- Folder Structure
SDK Guides & Examples
Although it might not make much sense in someone eyes to make a guide about a guide, I want to give some hints for what I’ve needed these documents for. So you won’t have to read through the whole documents.
There are 3 documents:
- SDK Guide & Examples: Next to the basic use principles of the API and some example for workflows, webServices etc. I’ve used it mainly for setting up my Eclipse Workspace, in order to create Java widgets/servlets/extensions. The guide for setting this up is pretty good („4.3. Workspace Preparation). Although I might have a simple remark: When setting up the eclipse environment you have to deactivate the linux plugins (ofc in windows), which are shipped with the Polarion libraries.
- Widget SDK Guide & Examples: You will need this pretty often, when developing reports and widgets. Here you find a lot of information about velocity widgets but the main things you will be searching for are the chapters „6.6 How to use Page Parameters in Velocity and Queries“ and „10 Velocity Context Reference“.
You’ll need the chapter 6.6 almost every time, when you want to access a page parameter, as you’ve forgotten how to access this specific type. Because they are always handled differently: Strings are other than Enums, Enums itself will be handled differently when being multi… and so on.
You’ll need the chapter 10 almost everytime you’re writing a new report or Velocity widget, as there is explained which „entry points“ you can use. There is basically described which variables are available from scratch. - Resource Traceability SDK Guide & Examples: Actually I’ve never used this document. As the resource traceability of Polarion only supports a few programming languages like java, (xml), c and others, you can create your own one. Maybe tracing files not even part of code. But most of the time linked revisions are enough. (If you don’t know what I’m talking about: go into the Polarion Help, that you can access in Polarion and search for these terms).
Polarion Open Java API „Open API“
In this topic you will find the link to the „API Documentation“, where you can see all classes and their methods. If you click on the link, then you will be lead to the Polarion ALM Open API Javadoc. Most of the time you will be lead to the overview of packages first. These are rather uninteresting. Click on „All Classes“ or „Frames“ To see the classes.
The Frames View isn’t available since Polarion 2304 anymore. But it’s just one possibility to view information. Now I’m using the search function in the upper right to find methods and classes.
I highly recommend the „Frames“ view, as it gives the fastest access to the information you need.
This way you can search for a class and methods in the same window. You can use CTRL+F to search for a class (will be shown on the bottom left), click on it and then you’ll see the methods on the right side.
Polarion Rendering API („Rendering API)
Wait wooooot? Two APIs? When to use which?
Someone
Well, it’s not that easy to say. Generally: If you want to render (haha captain obvious) something, like Work Items with their icon and link, then you’ll most likely use the Rendering API. But sometimes it’s easier to get the data by the Open API. Then you’ll switch just for rendering from Open to Rendering API objects. (Most of the time you can get Rendering API objects by the Open API objects, but not the other way round).
But basically it’s the same principle behind the rendering API, as for the open API. Just the way it is structured is a bit different.
In the Rendering API you most likely start with the „ReadOnlyTransaction“ (Code: $transaction), which offers methods for all kind of objects like plans, work items and so on.
It is pretty straight forward in comparison to the Open API, where it is much less self-explaining (which doesn’t mean, that the rendering would be).
Polarion WebServices API
The WebServices are needed to do something with Polarion from the „outside“. Like an Importer or an Interface. You can’t use this API internally. It’s used from software, that logs into Polarion from outside, sets up a session and then executes something via these WebServices.
How you can use the WebService, can be found in the local Polarion installation under: „Polarion/polarion/sdk/examples/com.polarion.example.importer“. This is an example of a work item importer…
Database
Although every change will be saved in the repository, a PostgreSQL database is in the layer in between to create good performance for the users.
Here you will find the whole database schema. You might need this, if you configure your reports via SQL queries. While Lucene reaches his „end“ pretty fast considering link logic, you can basically do whatever you like with SQL Queries. And most widgets allow to be configured by SQL Queries.
It is not really complicated, although it looks like that on the first glance. Most of the time you’ll need just a hand full of tables. „WORKITEM“ and „STRUCT_WORKITEM_LINKEDWORKITEMS“ will be needed most of the time.
To create SQL queries, I tested my queries offline at a test version installation of Polarion. (Just get the testversion and install it locally) You can access the SQL Database of Polarion with the tool „PG Admin“. The default password for the PostgreSQL Database is „polarion“.
This way you can easily access the live SQL Database and create your own SQL queries and instantly test them.
Other Resources
I’ve never used anything of this. But especially the API change log is very interesting for IT Operations. If you have custom extensions, you might take a look in there and check, if something important has been removed. But I never had the experience, that something I developed didn’t work anymore.
Folder Structure
This folder structure can be found in your local Polarion installation and describes usefull examples for customizing and documentation.