Client

class rtcclient.client.RTCClient(url, username, password, email=None, proxies=None, searchpath=None, ends_with_jazz=True, verify: bool | str = False, old_rtc_authentication=False, **kwargs)[source]

A wrapped class for RTC Client to perform all related operations

Parameters:

  • url – the rtc url (e.g. https://your_domain:9443/jazz)

  • username – the rtc username

  • password – the rtc password

  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.

  • searchpath – (optional) the folder to store your templates. If None, the default search path (/your/site-packages/rtcclient/templates) will be loaded.

  • ends_with_jazz (bool) – (optional but important) Set to True (default) if the url ends with ‘jazz’, otherwise to False if with ‘ccm’ (Refer to issue #68 for details)

Tips: You can also customize your preferred properties to be returned by specified returned_properties when the called methods have this optional parameter, which can also GREATLY IMPROVE the performance of this client especially when getting or querying lots of workitems.

Important Note: returned_properties is an advanced parameter, the returned properties can be found in ClassInstance.field_alias.values(), e.g. myworkitem1.field_alias.values(). If you don’t care the performance, just leave it alone with None.

checkProjectAreaID(projectarea_id, archived=False)[source]

Check the validity of rtcclient.project_area.ProjectArea id

Parameters:
Returns:

True or False

Return type:

bool

checkType(item_type, projectarea_id)[source]

Check the validity of rtcclient.workitem.Workitem type

Parameters:
Returns:

True or False

Return type:

bool

copyWorkitem(copied_from, title=None, description=None, prefix=None)[source]

Create a workitem by copying from an existing one

Parameters:

  • copied_from – the to-be-copied workitem id

  • title – the new workitem title/summary. If None, will copy that from a to-be-copied workitem

  • description – the new workitem description. If None, will copy that from a to-be-copied workitem

  • prefix – used to add a prefix to the copied title and description

Returns:

the rtcclient.workitem.Workitem object

Return type:

rtcclient.workitem.Workitem

createWorkitem(item_type, title, description=None, projectarea_id=None, projectarea_name=None, template=None, copied_from=None, keep=False, **kwargs)[source]

Create a workitem

Parameters:

  • item_type – the type of the workitem (e.g. task/defect/issue)

  • title – the title of the new created workitem

  • description – the description of the new created workitem

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • template – The template to render. The template is actually a file, which is usually generated by rtcclient.template.Templater.getTemplate and can also be modified by user accordingly.

  • copied_from – the to-be-copied workitem id

  • keep – refer to keep in rtcclient.template.Templater.getTemplate. Only works when template is not specified

  • kwargs – Optional/mandatory arguments when creating a new workitem. More details, please refer to kwargs in rtcclient.template.Templater.render

Returns:

the rtcclient.workitem.Workitem object

Return type:

rtcclient.workitem.Workitem

getFiledAgainst(filedagainst_name, projectarea_id=None, projectarea_name=None, archived=False)[source]

Get rtcclient.models.FiledAgainst object by its name

Parameters:

  • filedagainst_name – the filedagainst name

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the filedagainst is archived

Returns:

the rtcclient.models.FiledAgainst object

Return type:

rtcclient.models.FiledAgainst

getFiledAgainsts(projectarea_id=None, projectarea_name=None, archived=False)[source]

Get all rtcclient.models.FiledAgainst objects by project area id or name

If both projectarea_id and projectarea_name are None, all the filedagainsts in all project areas will be returned.

If no rtcclient.models.FiledAgainst objects are retrieved, None is returned.

Parameters:

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the filedagainsts are archived

Returns:

a list that contains all the rtcclient.models.FiledAgainst objects

Return type:

list

getFoundIn(foundin_name, projectarea_id=None, projectarea_name=None, archived=False)[source]

Get rtcclient.models.FoundIn object by its name

Parameters:

  • foundin_name – the foundin name

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the foundin is archived

Returns:

the rtcclient.models.FoundIn object

Return type:

rtcclient.models.FoundIn

getFoundIns(projectarea_id=None, projectarea_name=None, archived=False)[source]

Get all rtcclient.models.FoundIn objects by project area id or name

If both projectarea_id and projectarea_name are None, all the foundins in all project areas will be returned.

If no rtcclient.models.FoundIn objects are retrieved, None is returned.

Parameters:

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the foundins are archived

Returns:

a list that contains all the rtcclient.models.FoundIn objects

Return type:

list

getPlannedFor(plannedfor_name, projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]

Get rtcclient.models.PlannedFor object by its name

Parameters:

  • plannedfor_name – the plannedfor name

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the plannedfor is archived

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

Returns:

the rtcclient.models.PlannedFor object

Return type:

rtcclient.models.PlannedFor

getPlannedFors(projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]

Get all rtcclient.models.PlannedFor objects by project area id or name

If both projectarea_id and projectarea_name are None, all the plannedfors in all project areas will be returned.

If no rtcclient.models.PlannedFor objecs are retrieved, None is returned.

Parameters:
Returns:

a list that contains all the rtcclient.models.PlannedFor objects

Return type:

list

getPriorities(projectarea_id=None, projectarea_name=None)[source]

Get all rtcclient.models.Priority objects by project area id or name

At least either of projectarea_id and projectarea_name is given.

If no rtcclient.models.Priority is retrieved, None is returned.

Parameters:
Returns:

a list contains all the rtcclient.models.Priority objects

Return type:

list

getPriority(priority_name, projectarea_id=None, projectarea_name=None)[source]

Get rtcclient.models.Priority object by its name

At least either of projectarea_id and projectarea_name is given

Parameters:
Returns:

the rtcclient.models.Priority object

Return type:

rtcclient.models.Priority

getProjectArea(projectarea_name, archived=False, returned_properties=None)[source]

Get rtcclient.project_area.ProjectArea object by its name

Parameters:

  • projectarea_name – the project area name

  • archived – (default is False) whether the project area is archived

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

Returns:

the rtcclient.project_area.ProjectArea object

Return type:

rtcclient.project_area.ProjectArea

getProjectAreaByID(projectarea_id, archived=False, returned_properties=None)[source]

Get rtcclient.project_area.ProjectArea object by its id

Parameters:
Returns:

the rtcclient.project_area.ProjectArea object

Return type:

rtcclient.project_area.ProjectArea

getProjectAreaID(projectarea_name, archived=False)[source]

Get rtcclient.project_area.ProjectArea id by its name

Parameters:

  • projectarea_name – the project area name

  • archived – (default is False) whether the project area is archived

Returns:

the string object

Return type:

string

getProjectAreaIDs(projectarea_name=None, archived=False)[source]

Get all rtcclient.project_area.ProjectArea id(s) by project area name

If projectarea_name is None, all the rtcclient.project_area.ProjectArea id(s) will be returned.

Parameters:

  • projectarea_name – the project area name

  • archived – (default is False) whether the project area is archived

Returns:

a list that contains all the ProjectArea ids

Return type:

list

getProjectAreas(archived=False, returned_properties=None)[source]

Get all rtcclient.project_area.ProjectArea objects

If no rtcclient.project_area.ProjectArea objects are retrieved, None is returned.

Parameters:

  • archived – (default is False) whether the project area is archived

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

Returns:

A list that contains all the rtcclient.project_area.ProjectArea objects

Return type:

list

getSeverities(projectarea_id=None, projectarea_name=None)[source]

Get all rtcclient.models.Severity objects by project area id or name

At least either of projectarea_id and projectarea_name is given

If no rtcclient.models.Severity is retrieved, None is returned.

Parameters:
Returns:

a list that contains all the rtcclient.models.Severity objects

Return type:

list

getSeverity(severity_name, projectarea_id=None, projectarea_name=None)[source]

Get rtcclient.models.Severity object by its name

At least either of projectarea_id and projectarea_name is given

Parameters:
Returns:

the rtcclient.models.Severity object

Return type:

rtcclient.models.Severity

getTeamArea(teamarea_name, projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]

Get rtcclient.models.TeamArea object by its name

If projectarea_id or projectarea_name is specified, then the matched rtcclient.models.TeamArea in that project area will be returned. Otherwise, only return the first found rtcclient.models.TeamArea with that name.

Parameters:

  • teamarea_name – the team area name

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • archived – (default is False) whether the team area is archived

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

Returns:

the rtcclient.models.TeamArea object

Return type:

rtcclient.models.TeamArea

getTeamAreas(projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]

Get all rtcclient.models.TeamArea objects by project area id or name

If both projectarea_id and projectarea_name are None, all team areas in all project areas will be returned.

If no rtcclient.models.TeamArea objects are retrieved, None is returned.

Parameters:
Returns:

a list that contains all the rtcclient.models.TeamArea objects

Return type:

list

getTemplate(copied_from, template_name=None, template_folder=None, keep=False, encoding='UTF-8')[source]

Get template from some to-be-copied workitems

More details, please refer to rtcclient.template.Templater.getTemplate

getTemplates(workitems, template_folder=None, template_names=None, keep=False, encoding='UTF-8')[source]

Get templates from a group of to-be-copied workitems and write them to files named after the names in template_names respectively.

More details, please refer to rtcclient.template.Templater.getTemplates

getWorkitem(workitem_id, returned_properties=None, skip_full_attributes=True)[source]

Get rtcclient.workitem.Workitem object by its id/number

Parameters:

  • workitem_id – the workitem id/number (integer or equivalent string)

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

  • skip_full_attributes – flag to retrieve all attributes.

Returns:

the rtcclient.workitem.Workitem object

Return type:

rtcclient.workitem.Workitem

getWorkitems(projectarea_id=None, projectarea_name=None, returned_properties=None, archived=False, skip_full_attributes=True)[source]

Get all rtcclient.workitem.Workitem objects by project area id or name

If both projectarea_id and projectarea_name are None, all the workitems in all project areas will be returned.

If no rtcclient.workitem.Workitem objects are retrieved, None is returned.

You can also customize your preferred properties to be returned by specified returned_properties

Parameters:
Returns:

a list that contains all the rtcclient.workitem.Workitem objects

Return type:

list

listFields(template)[source]

List all the attributes to be rendered from the template file

Parameters:

template – The template to render. The template is actually a file, which is usually generated by rtcclient.template.Templater.getTemplate and can also be modified by user accordingly.

Returns:

a set that contains all the needed attributes

Return type:

set

More details, please refer to rtcclient.template.Templater.listFieldsFromWorkitem

listFieldsFromWorkitem(copied_from, keep=False)[source]

List all the attributes to be rendered directly from some to-be-copied workitems

More details, please refer to rtcclient.template.Templater.listFieldsFromWorkitem

queryWorkitems(query_str, projectarea_id=None, projectarea_name=None, returned_properties=None, archived=False)[source]

Query workitems with the query string in a certain project area

At least either of projectarea_id and projectarea_name is given

Parameters:

  • query_str – a valid query string

  • projectarea_id – the rtcclient.project_area.ProjectArea id

  • projectarea_name – the project area name

  • returned_properties – the returned properties that you want. Refer to rtcclient.client.RTCClient for more explanations

  • archived – (default is False) whether the workitems are archived

Returns:

a list that contains the queried rtcclient.workitem.Workitem objects

Return type:

list

relogin()[source]

Relogin the RTC Server/Jazz when the token expires