Polarion LiveDoc

Usage

This chapter details some common operations on Polarion LiveDocs

Creating and accessing a document

Documents are located in spaces in Polarion. To create a document, a space needs to be indicated. Additionally, the list of item types and the link role for structural relationships (usually ‘relates_to’) are needed. The example below creates a document and retrieves it again.

spaces = project.getDocumentSpaces()
document = project.createDocument(spaces[0], 'A new document', 'The document title', ['task'], 'relates_to')
document = project.getDocument(f'spaces[0]/{document.name}')

Document headings

Headings are used to group workitems in a document. Headings can be created as children of other headings or on the top level.

chapter_1 = document.addHeading('Chapter 1')
document.addHeading('Chapter 1.1', chapter_1)

Work items in a document

Work items in a Polarion document are organized as a tree. By getting the top level item, you can iterate through all items by traversing their children in the document. Additionally, you can get the parent of a workitem.

top_work_item = document.getTopLevelWorkitem()
children = document.getChildren(top_work_item)
for child in children:
    print(child)
    print(document.getParent(child))

As an alternative, you can just get all work items in a document and work with them as a list.

work_items = document.getWorkitems()
for work_item in work_items:
    print(work_item)

Workitems can be added to documents as children of another workitem in the document.

work_item = project.createWorkItem('task')
work_item.moveToDocument(work_item, document.getTopLevelWorkitem())

Reusing documents

It is possible to reuse documents with all contained workitems. The reused document can be updated to reflect the changes done in the original document. In the following example, an existing document is reused, changed and the reused document is updated to the head revision.

reused_document = original_document.reuse(project.id, '_default', 'Reused document', 'derived_from')
original_document.getTopLevelWorkitem().setDescription('Changed description')
reused_document.update()

Custom fields

If the document 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.

document.setCustomField('string_field', 'new string')
document.setCustomField('int_field', 99)
document.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 document 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'))
document.setCustomField('multi_enum_field', enum_array)

Note that Polarion does not support checking custom field availability for documents, so make sure that the document has the custom field configured before setting it.

Document class

class polarion.document.Document(polarion, project, uri=None, location=None)
addHeading(title, parent_workitem=None)

Adds a heading to a document

Parameters:

  • title – Title of the heading

  • parent_workitem – Parent workitem in the document hierarchy, set to None to create it on top level

Returns:

Heading workitem

delete()

Deletes a document

exportDocumentToPDF()

Download a PDF export of the document. :return: bytes

getChildren(workitem)

Gets the children of a workitem in the document.

Parameters:

workitem – Workitem to get children for

Returns:

List of workitems

getParent(workitem)

Gets the parent of a workitem in the document.

Parameters:

workitem – Workitem to get parent for

Returns:

Parent workitem, None if no parent

getTopLevelWorkitem()

Get the top level workitem, which is usually the title. :return: Workitem

getWorkitemUris()

Get the uris of all workitems in the document. :return: string[]

getWorkitems()

Get all complete workitems. That may take some time on a large document. :return: Workitem[]

isCustomFieldAllowed(_)

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

The Polarion interface to get allowed custom fields only supports work items.

Returns:

If the field is allowed

Return type:

bool

reuse(target_project_id, target_location, target_name, target_title, link_role='derived_from', derived_fields=None)

Reuse this document in a different project.

Parameters:

  • target_project_id – The target project id

  • target_location – Location of the target document

  • target_name – The target document’s name

  • target_title – Title of the target document

  • link_role – Link role of the derived documents, None for no linking

  • derived_fields – List of fields to be derived in the target document

Returns:

The new document

save()

Update the document in polarion

update(revision=None, auto_suspect=False)

Update a reused document to a revision of the source document.

Parameters:

  • revision – Source document revision

  • auto_suspect – If set to True, changed workitems will mark their links as suspect