Package: mlx.jira-traceability
IntroductionSphinx plugin for creating Jira tickets based on traceable items that have been added bymlx.traceability. You can look at this module as an extension for
mlx.traceability.UsageJira Ticket CreationJira tickets that are based on traceable items can be automatically created by the plugin. A ticket gets created only
for each item of which its IDmatchesthe configured regular expressionitem_to_ticket_regex.
Duplication of tickets is avoided by querying Jira first for existing tickets based on the Jira project and the
value of the ticket field configured byjira_field_id. Below is an example configuration:Configurationextensions=['mlx.traceability','mlx.jira_traceability',]traceability_jira_automation={'api_endpoint':'https://example.atlassian.com','username':'abc@example.com','password':'my_api_token','item_to_ticket_regex':r'ACTION-12345_ACTION_\d+','jira_field_id':'summary','issue_type':'Task','project_key_regex':r'ACTION-(?P<project>\d{5})_','project_key_prefix':'MLX',# MLX12345 for example'default_project':'SWCC','relationship_to_parent':('depends_on',r'MEETING-[\w_]+'),'components':'[SW],[HW]','description_head':'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\n\n','description_str_to_attr':{'<<file_name>>':'docname'},'warn_if_exists':False,'errors_to_warnings':True,'notify_watchers':False,}Jira ConfigurationJira Serverapi_endpoint:https://jira.example.com/jirausername:abcpassword:my_passwordJira Cloudapi_endpoint:https://example.atlassian.comusername:abc@example.compassword:my_api_tokenPlugin Configurationproject_key_regexcan optionally be defined. This regular expression with a named groupprojectis used to
extract a certain part of the item ID to determine the Jira project key.project_key_prefixcan optionally be
defined to add a prefix to the match forproject_key_regex. Additionally,default_projectdefines the Jira
project key or id in case the regular expression doesn’t come up with a match or hasn’t been configured.item_to_ticket_regexdefines the regular expression used to filter item IDs to be exported as Jira tickets.
A warning gets reported when a Jira ticket already exists. These warnings can be disabled by settingwarn_if_existstoTrue. Errors raised by Jira are converted to warnings by default. If you want these errors to
crash your build, you can seterrors_to_warningsto a falsy value.The item ID of a linked item can be added to the summary of the Jira ticket to create by specifying the relationship
to this item in the value for settingrelationship_to_parent. The value can be a list or tuple with the relationship
as the first element and the regular expression to match the linked item’s ID as the second element.
This feature makes it possible to create a query link in advance to list all Jira tickets that are related to this
linked item.A string can be added to the start of a ticket’s description by configuringdescription_head. If the item to create
a ticket for does not have a body, its caption will be used to build the ticket’s description.Watchers of a ticket can be notified about the creation of the ticket by settingnotify_watcherstoTrue.
Note that this notification is only sent when the user to assign to the ticket is different from the default assignee
configured in Jira.AttributesAll attributes are optional and are defined inthe default configuration of mlx.traceability.assigneeis used to assign a username to the Jira ticket.effortis used to set the original effort estimation field. On failure, it gets appended to the description field.If the item for which to create a ticket has an item linked to it by arelationship_to_parentrelationship,
theattendeesattribute of this linked item should be a comma-separated list of usernames that get added as watchers
to the ticket.Mapping of Strings to Item Attributes (advanced)If you want to use the value of an attribute of a TraceableItem in the string value for thedescription_headsetting, you can set thedescription_str_to_attrsetting to a dictionary mapping the string you
want to have replaced to the attribute of theTraceableItemthat should take its place. In the following example,
some placeholder text will get replaced by the document name the item is located in:'description_head':'Action raised in [this meeting|https://docserver.com/<<file_name>>.html].\n\n','description_str_to_attr':{'<<file_name>>':'docname'}