Polarion work items

Usage

This chapter details some common operations.

Creating a new workitem

A new workitem can be created using createWorkitem().

new_task = project.createWorkitem('changerequest')

# Add fields to the creation. Needed if there are required fields upon creation.
new_task = project.createWorkitem('task', new_workitem_fields={'title': 'New title'})

Updating a field

The workitem can be updated and saved. The example below loads a workitem, changes the title and loads it again to show the changes have happened in Polarion.

workitem = project.getWorkitem('PYTH-510')
print(f'Title: {workitem.title}')
print(f'Status: {workitem.status.id}')
print(f'Type: {workitem.type.id}')
workitem.title = 'A custom new title!'
workitem.save()

reload_workitem = project.getWorkitem('PYTH-510')
print(f'Title: {reload_workitem.title}')
print(f'Status: {reload_workitem.status.id}')
print(f'Type: {reload_workitem.type.id}')

Prints:

Title: title?
Status: open
Type: task
Title: A custom new title!
Status: open
Type: task

Setting a new status

Polarion status changes can be made by choosing one fo the available options for the workitem.

workitem = project.getWorkitem('PYTH-510')
print(f'Status: {workitem.status.id}')
actions = workitem.getAvailableActions()
print(f' Actions: {actions}')

workitem.preformAction(actions[0])

reload_workitem = project.getWorkitem('PYTH-510')
print(f'Status: {reload_workitem.status.id}')

prints:

Status: open
Actions: ['start_progress', 'mark_done', 'mark_verified', 'reject']
Status: inprogress

The rules set in Polarion apply to these actions. Failing to meet the rules will result in an exception:

Exception has occurred: Fault
com.polarion.core.util.exceptions.UserFriendlyRuntimeException: 'Mark Done' failed for Work Item 'PYTH-510': The required field 'assignee' of Work Item 'PYTH-510' is empty

If a status requires other properties to be set, for example the resolution, then you can query options like so:

workitem = project.getWorkitem('PYTH-510')
print(f'Status: {workitem.status.id}')
actions = workitem.getAvailableActions()
print(f' Actions: {actions}')
resolutions = workitem.getResolutionEnum()
project_resolutions = project.getEnum('resolution')
print(f'Workitem resolutions: {resolutions}')
print(f'Project resolutions: {project_resolutions}')

workitem.setResolution(project_resolutions[11])
workitem.preformAction(actions[1])

reload_workitem = project.getWorkitem('PYTH-510')
print(f'Status: {reload_workitem.status.id}')

Print:

Status: open
Actions: ['start_progress', 'mark_done', 'mark_verified', 'reject']
Workitem resolutions: []
Project resolutions: ['done', 'valid', 'unsupported', 'wontdo', 'invalid', 'obsolete', 'duplicate', 'inactive', 'incomplete', 'other', 'cannotreproduce', 'later']
Status: done

In this case not workitem specific resolutions are available (Polarion project setting) so only the project resolutions can be used.

Warning

Currently there is no option available to check which resolutions are correct for the workflow defined in Polarion. You can set any resolution.

Changing the assignee

The assignee can be changed by getting a user from the project and setting it as assignee.

workitem = project.getWorkitem('PYTH-524')
j = project.findUser('john')
workitem.addAssignee(j)

Test case workitem

Some workitems are test cases and can contain test steps. Use hasTestSteps() to determine if there are test steps.

A general example of working with test steps:

wi = prj.getWorkitem('PYTH-515')
print(wi.getTestStepHeader())

for i in range(3):
    wi.addTestStep(f'Step {i}', '', '')

print(wi.getTestSteps())

wi.removeTestStep(0)

Attachments

A workitem may have an attachment. An example for working with attachments:

workitem = project.getWorkitem('PYTH-524')
#upload a file
workitem.addAttachment(path_to_file, 'file title')
workitem.hasAttachment() # now true
#download a file
attachment_id = workitem.attachments.TestRunAttachment[0].id
workitem.saveAttachmentAsFile(attachment_id, path_to_new_file)
#update a file
workitem.updateAttachment(attachment_id, path_to_file, 'file title')
#deleting attachment
workitem.deleteAttachment(attachment_id)

Linking

Workitems can be linked together using addLinkedItem(). In this example new_workitem_2 ‘relates to’ new_workitem_1. new_workitem_1 will have the oppoite ‘is related to’ link.

new_workitem_2.addLinkedItem(new_workitem_1, 'relates_to')

Links can be retrieved either with or without link roles:

print(workitem_1.getLinkedItem()) # [PYTH-540: None]
print(workitem_1.getLinkedItemWithRoles()) # [('follow_up', PYTH-540: None)]

Custom fields

If the workitem has any custom fields, they will be accessible via the customFields property. The method setCustomField() is available to set custom field values. This method will create the custom field structure if not available.

workitem1.setCustomField('string_field', 'new string')
workitem1.setCustomField('int_field', 99)
workitem1.setCustomField('custom_enum_field', client.EnumOptionIdType(id='okay'))

Enums can be configured so that multiple options can be selected. This is not supported via the workitem class, but can be achieved manually.

enum_array = client.ArrayOfEnumOptionIdType()
enum_array.EnumOptionId.append(client.EnumOptionIdType(id='open'))
enum_array.EnumOptionId.append(client.EnumOptionIdType(id='done'))
workitem1.setCustomField('multi_enum_field', enum_array)

Disabled features in Polarion

It has been reported that the addComment function can be disabled in Polarion. An exception will be thrown if this is the case in a specific Polarion instance.

Helpers

The workitem class implements the __eq__ method allowing it to be compared.

workitem1 = project.getWorkitem('PYTH-524')
workitem2 = project.getWorkitem('PYTH-525')

if workitem1 == workitem2:
#...

Context Manager

It is possible to use the context manager with a workitem. This is useful, when updating many attributes of it. Execution speed increases, because the workitem is only updated / saved once, when exiting the context manager.

with workitem as wi:
    wi.addAttachment(path_to_file, 'file title')
    wi.addComment('comment')
    # any many more

List of available attributes

The attributes are set in the workitem when loading it from polarion. An attribute can be None (when it is not set), a string, number or datetime, or another object. When accessing any attribute, a check for None is recommended as the only attributes that are always set are: -Author -Type -Created -Project

Other attributes that will be available, but could be None, are listed below. Some objects only have one attribute, named id, these values can be accessed directly if not None. If they are None and you want to set them, use the setter method listed below.

Attribute

Type (when not None)

getter

setter

approvals

No

No

assignee

object

addAssignee

removeAssignee

getAssignedUsers

attachments

No

No

author

object

getAuthor

No

categories

No

No

comments

object

No

addComment

created

datetime

No

No

customFields

No

setCustomField

description

object

getDescription

setDescription

dueDate

No

No

externallyLinkedWorkItems

No

No

hyperlinks

No

addHyperlink

id

string

No

No

initialEstimate

string

No

No

linkedOslcResources

No

No

linkedRevisions

No

No

linkedRevisionsDerived

No

No

linkedWorkItems

No

addLinkedItem

linkedWorkItemsDerived

No

No

location

string

No

No

moduleURI

No

No

outlineNumber

No

No

plannedEnd

No

No

plannedIn

No

No

plannedStart

No

No

planningConstraints

No

No

previousStatus

previousStatus.id

object (id)

string

No

No

priority

priority.id

object (id)

string

No

No

project

object

No

No

remainingEstimate

string

No

No

removeAssignee

No

No

resolution

resolution.id

object (id)

string

No

setResolution

resolvedOn

No

No

severity

severity.id

object (id)

string

No

No

status

status.id

object (id)

string

No

preformAction

setStatus (not prefered)

timePoint

No

No

timeSpent

No

No

title

string

No

No

type

type.id

object (id)

string

No

No

unresolvable

boolean

No

No

updated

datetime

No

No

uri

string

No

No

workRecords

No

No

Workitem class

class polarion.workitem.Workitem(polarion, project, id=None, uri=None, new_workitem_type=None, new_workitem_fields=None, polarion_workitem=None)

Create a Polarion workitem object either from and id or from an Polarion uri.

Parameters:

  • polarion – Polarion client object

  • project – Polarion Project object

  • id – Workitem ID

  • uri – Polarion uri

  • polarion_workitem – Polarion workitem content

class HyperlinkRoles(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Hyperlink reference type enum

addApprovee(user: User, remove_others=False)

Adds a user as approvee

Parameters:

  • user – The user object to add

  • remove_others – Set to True to make the new user the only approver user.

addAssignee(user: User, remove_others=False)

Adds a user as assignee

Parameters:

  • user – The user object to add

  • remove_others – Set to True to make the new user the only assigned user.

addAttachment(file_path, title)

Upload an attachment

Parameters:

  • file_path – Source file to upload

  • title – The title of the attachment

Adds a hyperlink to the workitem.

Parameters:

  • url – The URL to add

  • hyperlink_type – Select internal or external hyperlink. Can be a string for custom link types.

addLinkedItem(workitem, link_type)

Add a link to a workitem

Parameters:

  • workitem – A workitem

  • link_type – The link type

addTestStep(*args)

Add a new test step to a test case work item @param args: list of strings, one for each column @return: None

delete()

Delete the work item in polarion This does not remove workitem references from documents

deleteAttachment(id)

Delete an attachment.

Parameters:

id – The attachment id

getAllowedCustomKeys()

Gets the list of keys that the workitem is allowed to have.

Returns:

An array of strings of the keys

Return type:

string[]

getApproverUsers()

Get an array of approval users

Returns:

An array of User objects

Return type:

User[]

getAssignedUsers()

Get an array of assigned users

Returns:

An array of User objects

Return type:

User[]

getAttachment(id)

Get the attachment data

Parameters:

id – The attachment id

Returns:

list of bytes

Return type:

bytes[]

getAuthor()

Get the author of the workitem

Returns:

Author

Return type:

User

getAvailableActions()

Get all actions option for this workitem without details

Returns:

An array of strings of the actions

Return type:

string[]

getAvailableActionsDetails()

Get all actions option for this workitem with details

Returns:

An array of dictionaries of the actions

Return type:

dict[]

getAvailableStatus()

Get all available status option for this workitem

Returns:

An array of string of the statusses

Return type:

string[]

getDescription()

Get a comment if available. The comment may contain HTML if edited in Polarion!

Returns:

The content of the description, may contain HTML

Return type:

string

getLinkedItem()

Get linked workitems both linked and back linked item will show up.

@return: Array of Workitem @return:

getLinkedItemWithRoles()

Get linked workitems both linked and back linked item will show up. Will include link roles.

@return: Array of tuple (‘link type’, Workitem)

getResolutionEnum()

tries to get the resolution enum of this workitem type When it fails to get it, the list will be empty

Returns:

An array of strings of the resolutions

Return type:

string[]

getRevision() → int

Return the revision number of the work item. @return: Integer with revision number

getSeverityEnum()

tries to get the severity enum of this workitem type When it fails to get it, the list will be empty

Returns:

An array of strings of the severities

Return type:

string[]

getStatusEnum()

tries to get the status enum of this workitem type When it fails to get it, the list will be empty

Returns:

An array of strings of the statusses

Return type:

string[]

getTestStepHeader()

Get the Header names for the test step header. @return: List of strings containing the header names.

getTestStepHeaderID()

Get the Header ID for the test step header. @return: List of strings containing the header IDs.

getTestSteps()

Return a list of test steps. @return: Array of test steps

hasAttachment()

Checks if the workitem has attachments

Returns:

True/False

Return type:

boolean

hasTestSteps()

Checks if the workitem has test steps

Returns:

True/False

Return type:

boolean

isCustomFieldAllowed(key)

Checks if the custom field of a given key is allowed.

Returns:

If the field is allowed

Return type:

bool

moveToDocument(document, parent)

Move the work item into a document as a child of another workitem

Parameters:

  • document – Target document

  • parent – Parent workitem, None if it shall be placed as top item

performAction(action_name)

Perform selected action. An exception will be thrown if some prerequisite is not set.

Parameters:

action_name – string containing the action name

performActionId(actionId: int)

Perform selected action. An exception will be thrown if some prerequisite is not set.

Parameters:

actionId – number for the action to perform

removeApprovee(user: User)

Remove a user from the approvers

Parameters:

user – The user object to remove

removeAssignee(user: User)

Remove a user from the assignees

Parameters:

user – The user object to remove

Removes the url from the workitem @param url: url to remove @return:

removeLinkedItem(workitem, role=None)

Remove the workitem from the linked items list. If the role is specified, the specified link will be removed. If not specified, all links with the workitem will be removed

Parameters:

  • workitem – Workitem to be removed

  • role – the role to remove

Returns:

None

removeTestStep(index: int)

Remove a test step at the specified index. @param index: zero based index @return: None

save()

Update the workitem in polarion

saveAttachmentAsFile(id, file_path)

Save an attachment to file.

Parameters:

  • id – The attachment id

  • file_path – File where to save the attachment

setDescription(description)

Sets the description and saves the workitem

Parameters:

description – the description

setResolution(resolution)

Sets the resolution and saves the workitem

Parameters:

resolution – the resolution

setStatus(status)

Sets the status opf the workitem and saves the workitem, not respecting any project configured limits or requirements.

Parameters:

status – name of the status

updateAttachment(id, file_path, title)

Upload an attachment

Parameters:

  • id – The attachment id

  • file_path – Source file to upload

  • title – The title of the attachment

updateTestStep(index: int, *args)

Update a test step at the specified index. @param index: zero based index @param args: list of strings, one for each column @return: None