How to Navigate Polarions APIs – Some basic Tips

---

While it becomes pretty easy to achive your goal with the Polarion API, if you have experience and know where to search – it can be equally frustrating, if you don’t find the necessary classes, methods and starting points. In this post I want to share my „search-tactics“ in the Polarion API to find what I need.

In this post I will go trough the following topics:

• How to read the Polarion API
• How to navigate
• General tipps and experiences

Hint: If you want to have more information about the APIs, check out my other posts (I linked them at the bottom of this article)

How to read the Polarion API

First I wanted to clarify some basics of how to read the API, to guarantee an understanding of the following topics. For beginners in Polarion, just a few things are important. If you search for more details and a more precise documentation on how Javadocs work, you can search the internet about Javadocs in general, as the API documentation isn’t something proprietary for Polarion.

But let’s get to the topic now:

Attention! The Frames View isn’t available since release 2304 anymore. But this is just a way how the information is shown. Everything else stays true!

I recommend to use the „Frames“ view while navigating the API. If you go into one of the APIs, you will start in the „Overview“ (as shown on the left in Figure 1), which will provide you only with the Java packages. If you click on Frames you will have more relevant information on one glance – allowing you to use the browser search with „Ctrl + F“ more efficiently.

If you search in the Frames view with the built-in search of the browser (Ctrl + F), it will search in packages, classes and the selected class for matches. You can see in Figure 1 where is what.

Most of the time you will be searching for classes in the lower-left and click on it. This will open the class and all of it’s methods on right side. The class itself contains methods , that instances of this class can use. And in Figure 2 you will see how to read it:

Figure 2 shows the class „ReadOnlyTransaction“ of the Rendering API. If you use the method „workItems()“, you will be provided an instance of „WorkItems“. Now you can go into the class „WorkItems“ and use the methods of this class and so on. This way you will go from object to object, until you have the desired ones. See other posts for examples (linked at the bottom).

How to Navigate

„But how do I know, which class I need and how do I know where to start to get there and which methods do I have to use…“

My former self

Exactly those questions I want to answer:

• How do I find the classes I need in the first place?
• How do I get there, after I identified it?

So lets start with: How do I find the class I need?

No matter what, you first have to decide on which API you want to use. You can choose between: Open, Rendering and WebServices API. Short: WebServices just, if you want to access Polarion from the outside. Open and Rendering are internal. I made a blog post about deciding between those two, so check it out:
https://polarion.code.blog/2020/06/16/rendering-vs-open-api/

Most of the time you might check both – to see which will fit better for your purpose. Rule of thumb: if you want to visualize the objects in the end, use rendering.

Now to: How do I find the class I need in these APIs?
Normally I can differentiate between two tactics to find what I need:

• Top-Down
  I know the available starting points and explore from there on my possibilities. E.g. starting with the trackerService and see what I can get from there.
• Bottom-Up
  I know the class or method I need and start to see where I can get them from.

The top down approach is simply exploring what you can do. For Velocity there are several defined entry points in the APIs. Also in more detail in this blog post: https://polarion.code.blog/2020/06/16/rendering-vs-open-api/
So if you want to get test runs, you will start with the starting point for testing the „testManagementService“, if you want to have something regarding users/roles you would start with the „securityService“ and so on. You will then take a look on the available methods of these services and see if there is something that will provide you the necessary. I recommend to search via text search (Ctrl + f) for what you want. The names of classes and methods are in general what you think they would be. So if you want to get test runs, the testManagementService provides you with several methods to get a test run:

The bottom-up approach is the one you might use, if your target class is „burried“ in the API and not accessible via one or two levels from one of the defined starting points. And you don’t really know how to get them. So let’s say you know you want Test Runs. which would be in the Open API instances of ITestRun (it behaves like that and we could pretend as if, to keep it simple). Now we could simply select the ITestRun class/interface and select „use“ to see where this class is used:

It will show any method that uses ITestRun instances, but we are interested in the ones that return ITestRun:

And in this overview we see, that a lot of methods from the testManagementService provide ITestRun(s). (Keep in Mind: Velocity Widgets can’t use writing methods like createTestRun)
But this is an easy example. It might happen, that you would have to go trough multiple steps to reach a starting point.

The same principle can be used, if you know which method you need. So lets say you know what you want to do. E.g. get a test run. Then you could go to the index, that lists all available methods in alphabetic order. It’s very likely that there is a method „getTestRun“. So you can go to the Index, go to the letter „G“ and search (CTRL + F) for „getTestRun“.

This will list all methods with this name and in which classes they appear. Then you could go again to the class and search bottom-up how to get an instance of it.

General Tipps and Experiences

Here I will list some additional tipps, that I couldn’t squeeze into the agenda above.

1. Use .class to see which class your object has. This is especially needed, if in the API documentation there is just something like „IPObjectList“ as return object. E.g. the method „queryWorkItems“ in the trackerService:

You don’t know here which kind of objects there will be in the list. You kind of know, that they are IPObjects – which are a superinterface of the IWorkItem interface, but you’re not sure what you really got in return.
So lets say I want to know which class the returned objects have, I have to iterate trough the list and check their class.

You can check that in a report page with a script block very quickly:

#set($projectId = $page.reference.projectId)
#set($projectService = $trackerService.getProjectService())
#set($project = $projectService.getProject($projectId))

#set($listOfWI = $trackerService.queryWorkItems($project, "type:task", "id"))
$listOfWI.class
#foreach($workItem in $listOfWI)
	$workItem.class<br>
#end

Here we see, that the objects in the returned list are „com.polarion.alm.tracker.internal.model.WorkItem“ objects. You might see, that this class doesn’t really appear in the API. And here comes the next tip into play.

2. Don’t mix up WebService classes in the OpenAPI. Almost all of the internal classes are documented via their interface classes (IWorkItem, ITrackerService etc.). Although there is a class „WorkItem“ in the OpenAPI, this is the one from the WebService. You can recognize them via their package name, there is a „ws“ in there:

You’re searching for these classes:

3. LiveDocs are called Modules in the OpenApi. Although there are „Documents“, these aren’t the current LiveDocs, but 2013 documents of Polarion (deprecated). So be aware, that you’re searching for modules, if you search for the current LiveDocs in the API.

4. The „objectFactory“ is your friend, if you want to use things like maps. As the Velocity version in Polarion is 1.4 and lacks some usefull tools like a map. You can still use one by creating one using the ObjectFactory.

Further Information about this Topic