Client

class rtcclient.client.RTCClient(url, username, password, searchpath=None, ends_with_jazz=True)[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
  • searchpath – 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) 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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:
  • (default is False) (archived) – 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
  • (default is False) (archived) – 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)[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
Returns:

the rtcclient.workitem.Workitem object
Return type:

rtcclient.workitem.Workitem
getWorkitems(projectarea_id=None, projectarea_name=None, returned_properties=None, archived=False)[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
  • (default is False) (archived) – whether the workitems are archived
Returns:

a list that contains the queried rtcclient.workitem.Workitem objects
Return type:

list