Rendering vs Open API

---

When to use Rendering and when to use the Open API of Polarion – A question often asked. Which I’m trying to make a little bit clearer.

This post is based upon my experience with the APIs. I’m aware of the fact, that some things I’m explaining may not be perfect. Maybe there are ways in the APIs, which are more efficient, than the ones I know of. In this case I would be glad, if you leave a comment.

Nevertheless I want to write this post, to share my knowledge to this point, which should still help beginners.

So lets start.

„Trying to put it simple: Rendering API for Rendering and Open API for data gathering & changes.“

Captain Obvious

But as most things in life: it’s not that simple.

Sometimes it’s way easier to get data via Open API and then switching the objects to Rendering API. Sometimes it’s easier to get data with the Rendering API in the first place. The truth is: it depends greatly on what you want to do.

For everyone who does not know, what I’m talking about. I’m talking about these API documentations in the Polarion SDK. You can find the Polarion sdk on any Polarion instance under: „[YourPolarionURL]/polarion/sdk/index.html“ or publicly here: https://testdrive.polarion.com/polarion/sdk/index.html

So lets go trough it in a structured way:

• Entry points
• Capabilities
• Complexity

I will only be able to show some examples. But hopefully it will give an impression of the basic principles.

Entry points

Open API allows to be entered with the following services, which are available everywhere (full list: Chapter 10 in https://testdrive.polarion.com/polarion/sdk/doc/widget-sdk.pdf):

Note: You can use these entry points in Velocity by setting a „$“ in front of the variable. So you can access the trackerService by using „$trackerService“.

trackerService (com.polarion.alm.tracker.ITrackerService)
Probably one of the most used services in the Open API. This service has very helpful methods like:
– queryWorkItems(..) – Allows you to get a list of Work Items based on a Lucene Query.
– getDataService & others – Allows to get Data Service and other Services / Managers with a wide range of functions.

projectService (com.polarion.alm.projects.IProjectService)
Used and needed, when searching projects and users.

securityService (com.polarion.platform.security.ISecurityService)
Needed, when you want to manage roles and access rights via API.

platformService (com.polarion.platform.IPlatformService)
… Just two methods: getting name and version of the installed Polarion.

testManagementService (com.polarion.alm.tracker.ITestManagementService)
Probably the second most used service here: This one is needed, if you want to access the testing data. Like test results, iterations, test runs and so on.

Now lets take a look at the Rendering API entry points:

transaction (com.polarion.alm.shared.api.transaction.ReadOnlyTransaction)
This is THE entry point for the rendering API. Well, not the only one, but the most relevant one. Here you can get a lot of different things. And it’s very readable listed:

localization (com.polarion.alm.shared.api.utils.SharedLocalization)
Not very interesting. Gives some data & time things.

Capabilities

Now lets go a step deeper. Lets take Work Items as an example, as it is one of the most common use cases, to get Work Items and render them.

In the Open API, you would use the trackerService and queryWorkItems method. This brings us very fast the list of Work Items we are searching for.

## Get the project object, which is needed for the queryWorkItems method
#set($projectId = $page.fields().project().projectId())
#set($project = $projectService.getProject($projectId))

## Get the Work Items
#set($sysReqs = $trackerService.queryWorkItems($project, "type:systemrequirement", "id"))
#foreach($sysReq in $sysReqs)
	$sysReq.getId()
#end

But if we would like to render the Work Item, we have to work with the attributes id and name or have to create hyperlinks manually via html to the Work Items.

So lets take a look at how this would look like in the Rendering API. First we would go to the ReadOnlyTransaction (entry Point) and use the method „workItems()“ the class WorkItems already allows us to use the method „search()“ and „getBy()“. (For navigating through the API I will release another post).

The „search()“ method provides an instance of class „ModelObjectsSearch“, which can use the method „query()“. This does basically the same as „queryWorkItems“ of the Open API. So if we use this method, we could render all System Requirements of the project with the following code:

## Get Project Id
#set($projectId = $page.fields().project().projectId())

## Get Work Items with new API
#set($renderWIs = $transaction.workItems().search().query("type:systemrequirement AND project.id:$projectId"))

## Render Work Items
#foreach($WI in $renderWIs)
	$WI.render().withLinks()<br>
#end

We can also get Work Items by id or the Open API object. Therefore we would have to use the method „getBy()“ of the class „WorkItems“. This will give us the WorkItemSelector, allowing to get Work Items by Id, but also by „oldApiObject“. This is quite handy.

This could be useful, if you’ve got a list of Open API Work Items, but want them to be rendered.

## Get project object
#set($projectId = $page.fields().project().projectId())
#set($project = $projectService.getProject($projectId))

## Using Old API to get Work Items
#set($sysReqs = $trackerService.queryWorkItems($project, "type:systemrequirement", "id"))
## Rendering Old API Work Items with Rendering API
#foreach($sysReq in $sysReqs)
	$transaction.workItems().getBy().oldApiObject($sysReq).render().withLinks()<br>
#end

At these examples we can see, that the Rendering API is pretty powerful and offers Polarion like rendering capabilities with just one method „.render()“. It’s not even a problem, if you start with the Open API in the first place, as there is the possibility to „switch“ APIs at some point.

But while the Rendering API is more powerful in this scenario, it isn’t necessarily in others. Some things can only be done by the Open API. Which is most often the case, when you want to change things. Like permissions, fields etc., but also the rendering API has updateable objects.

Complexity

The two APIs are really different in the way they are structured. The Rendering API is „better“ structured (more readable and granular), but this is not necessarily better in all situations. With the Rendering API you will need on average more methods, before you get to things you need. While the Open API is more angled than the Rendering API, it is in some points more powerful.

Conclusion

In the end it will be a mixture of both APIs. I personally would recommend to use the Rendering API whenever possible and switch to Open API, when Rendering API reaches it’s limits. The greatest advantage of the rendering API is the easy Polarion like rendering capability it provides.