# 2. Examples

Contents

- Quickstart
  - Initialization
  - Authentication
    - HTTP BASIC
    - OAuth
    - Kerberos
  - Issues
  - Fields
  - Searching
  - Comments
  - Transitions
  - Projects
  - Watchers
  - Attachments

Here’s a quick usage example:

    # This script shows how to use the client in anonymous mode
    # against jira.atlassian.com.
    from jira import JIRA
    import re

    # By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK
    # (see https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK for details).
    # Override this with the options parameter.
    options = {
        'server': 'https://jira.atlassian.com'}
    jira = JIRA(options)

    # Get all projects viewable by anonymous users.
    projects = jira.projects()

    # Sort available project keys, then return the second, third, and fourth keys.
    keys = sorted([project.key for project in projects])[2:5]

    # Get an issue.
    issue = jira.issue('JRA-1330')

    # Find all comments made by Atlassians on this issue.
    atl_comments = [comment for comment in issue.fields.comment.comments
                    if re.search(r'@atlassian.com$', comment.author.emailAddress)]

    # Add a comment to the issue.
    jira.add_comment(issue, 'Comment text')

    # Change the issue's summary and description.
    issue.update(
        summary="I'm different!", description='Changed the summary to be different.')

    # Change the issue without sending updates
    issue.update(notify=False, description='Quiet summary update.')

    # You can update the entire labels field like this
    issue.update(labels=['AAA', 'BBB'])

    # Or modify the List of existing labels. The new label is unicode with no
    # spaces
    issue.fields.labels.append(u'new_text')
    issue.update(fields={"labels": issue.fields.labels})

    # Send the issue away for good.
    issue.delete()

    # Linking a remote jira issue (needs applinks to be configured to work)
    issue = jira.issue('JRA-1330')
    issue2 = jira.issue('XX-23')  # could also be another instance
    jira.add_remote_link(issue, issue2)

Another example shows how to authenticate with your JIRA username and password:

    # This script shows how to connect to a JIRA instance with a
    # username and password over HTTP BASIC authentication.

    from collections import Counter
    from jira import JIRA

    # By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK.
    # See
    # https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK
    # for details.
    jira = JIRA(basic_auth=('admin', 'admin'))    # a username/password tuple

    # Get the mutable application properties for this server (requires
    # jira-system-administrators permission)
    props = jira.application_properties()

    # Find all issues reported by the admin
    issues = jira.search_issues('assignee=admin')

    # Find the top three projects containing issues reported by admin
    top_three = Counter(
        [issue.fields.project.key for issue in issues]).most_common(3)

This example shows how to work with GreenHopper:

    # This script shows how to use the client in anonymous mode
    # against jira.atlassian.com.
    from jira.client import GreenHopper

    # By default, the client will connect to a JIRA instance started from the Atlassian Plugin SDK
    # (see https://developer.atlassian.com/display/DOCS/Installing+the+Atlassian+Plugin+SDK for details).
    # Override this with the options parameter.
    # GreenHopper is a plugin in a JIRA instance
    options = {
        'server': 'https://jira.atlassian.com'}
    gh = GreenHopper(options)

    # Get all boards viewable by anonymous users.
    boards = gh.boards()

    # Get the sprints in a specific board
    board_id = 441
    print("GreenHopper board: %s (%s)" % (boards[0].name, board_id))
    sprints = gh.sprints(board_id)

    # List the incomplete issues in each sprint
    for sprint in sprints:
        sprint_id = sprint.id
        print("Sprint: %s" % sprint.name)
        incompleted_issues = gh.incompleted_issues(board_id, sprint_id)
        print("Incomplete issues: %s" %
              ', '.join(issue.key for issue in incompleted_issues))

## 2.1. Quickstart

### 2.1.1. Initialization

Everything goes through the JIRA object, so make one:

    from jira import JIRA

    jira = JIRA()

This connects to a JIRA started on your local machine at http://localhost:2990/jira, which not coincidentally is the default address for a JIRA instance started from the Atlassian Plugin SDK.

You can manually set the JIRA server to use:

    jac = JIRA('https://jira.atlassian.com')

### 2.1.2. Authentication

At initialization time, jira-python can optionally create an HTTP BASIC or use OAuth 1.0a access tokens for user authentication. These sessions will apply to all subsequent calls to the JIRA object.

The library is able to load the credentials from inside the ~/.netrc file, so put them there instead of keeping them in your source code.

#### 2.1.2.1. HTTP BASIC

Pass a tuple of (username, password) to the `basic_auth` constructor argument:

    authed_jira = JIRA(basic_auth=('username', 'password'))

#### 2.1.2.2. OAuth

Pass a dict of OAuth properties to the `oauth` constructor argument:

    # all values are samples and won't work in your code!
    key_cert_data = None
    with open(key_cert, 'r') as key_cert_file:
        key_cert_data = key_cert_file.read()

    oauth_dict = {
        'access_token': 'd87f3hajglkjh89a97f8',
        'access_token_secret': 'a9f8ag0ehaljkhgeds90',
        'consumer_key': 'jira-oauth-consumer',
        'key_cert': key_cert_data
    }
    authed_jira = JIRA(oauth=oauth_dict)

Note

The OAuth access tokens must be obtained and authorized ahead of time through the standard OAuth dance. For interactive use, `jirashell` can perform the dance with you if you don’t already have valid tokens.

Note

OAuth in Jira uses RSA-SHA1 which requires the PyCrypto library. PyCrypto is not installed automatically when installing jira-python. See also the Dependencies. section above.

- The access token and token secret uniquely identify the user.
- The consumer key must match the OAuth provider configured on the JIRA server.
- The key cert data must be the private key that matches the public key configured on the JIRA server’s OAuth provider.

See https://confluence.atlassian.com/display/JIRA/Configuring+OAuth+Authentication+for+an+Application+Link for details on configuring an OAuth provider for JIRA.

#### 2.1.2.3. Kerberos

To enable Kerberos auth, set `kerberos=True`:

    authed_jira = JIRA(kerberos=True)

### 2.1.3. Issues

Issues are objects. You get hold of them through the JIRA object:

    issue = jira.issue('JRA-1330')

Issue JSON is marshaled automatically and used to augment the returned Issue object, so you can get direct access to fields:

    summary = issue.fields.summary         # 'Field level security permissions'
    votes = issue.fields.votes.votes       # 440 (at least)

If you only want a few specific fields, save time by asking for them explicitly:

    issue = jira.issue('JRA-1330', fields='summary,comment')

Reassign an issue:

    # requires issue assign permission, which is different from issue editing permission!
    jira.assign_issue(issue, 'newassignee')

Creating issues is easy:

    new_issue = jira.create_issue(project='PROJ_key_or_id', summary='New issue from jira-python',
                                  description='Look into this one', issuetype={'name': 'Bug'})

Or you can use a dict:

    issue_dict = {
        'project': {'id': 123},
        'summary': 'New issue from jira-python',
        'description': 'Look into this one',
        'issuetype': {'name': 'Bug'},
    }
    new_issue = jira.create_issue(fields=issue_dict)

You can even bulk create multiple issues:

    issue_list = [
    {
        'project': {'id': 123},
        'summary': 'First issue of many',
        'description': 'Look into this one',
        'issuetype': {'name': 'Bug'},
    },
    {
        'project': {'key': 'FOO'},
        'summary': 'Second issue',
        'description': 'Another one',
        'issuetype': {'name': 'Bug'},
    },
    {
        'project': {'name': 'Bar'},
        'summary': 'Last issue',
        'description': 'Final issue of batch.',
        'issuetype': {'name': 'Bug'},
    }]
    issues = jira.create_issues(field_list=issue_list)

Note

Project, summary, description and issue type are always required when creating issues. Your JIRA may require additional fields for creating issues; see the `jira.createmeta` method for getting access to that information.

Note

Using bulk create will not throw an exception for a failed issue creation. It will return a list of dicts that each contain a possible error signature if that issue had invalid fields. Successfully created issues will contain the issue object as a value of the `issue` key.

You can also update an issue’s fields with keyword arguments:

    issue.update(summary='new summary', description='A new summary was added')
    issue.update(assignee={'name': 'new_user'})    # reassigning in update requires issue edit permission

or with a dict of new field values:

    issue.update(fields={'summary': 'new summary', 'description': 'A new summary was added'})

You can suppress notifications:

    issue.update(notify=False, description='A quiet description change was made')

and when you’re done with an issue, you can send it to the great hard drive in the sky:

    issue.delete()

Updating components:

    existingComponents = []
    for component in issue.fields.components:
        existingComponents.append({"name" : component.name})
    issue.update(fields={"components": existingComponents})

### 2.1.4. Fields

> issue.fields.worklogs # list of Worklog objects issue.fields.worklogs[0].author issue.fields.worklogs[0].comment issue.fields.worklogs[0].created issue.fields.worklogs[0].id issue.fields.worklogs[0].self issue.fields.worklogs[0].started issue.fields.worklogs[0].timeSpent issue.fields.worklogs[0].timeSpentSeconds issue.fields.worklogs[0].updateAuthor # dictionary issue.fields.worklogs[0].updated

> issue.fields.timetracking.remainingEstimate # may be NULL or string (“0m”, “2h”…) issue.fields.timetracking.remainingEstimateSeconds # may be NULL or integer issue.fields.timetracking.timeSpent # may be NULL or string issue.fields.timetracking.timeSpentSeconds # may be NULL or integer

### 2.1.5. Searching

Leverage the power of JQL to quickly find the issues you want:

    issues_in_proj = jira.search_issues('project=PROJ')
    all_proj_issues_but_mine = jira.search_issues('project=PROJ and assignee != currentUser()')

    # my top 5 issues due by the end of the week, ordered by priority
    oh_crap = jira.search_issues('assignee = currentUser() and due < endOfWeek() order by priority desc', maxResults=5)

    # Summaries of my last 3 reported issues
    print [issue.fields.summary for issue in jira.search_issues('reporter = currentUser() order by created desc', maxResults=3)]

### 2.1.6. Comments

Comments, like issues, are objects. Get at issue comments through the parent Issue object or the JIRA object’s dedicated method:

    comments_a = issue.fields.comment.comments
    comments_b = jira.comments(issue) # comments_b == comments_a

Get an individual comment if you know its ID:

    comment = jira.comment('JRA-1330', '10234')

Adding, editing and deleting comments is similarly straightforward:

    comment = jira.add_comment('JRA-1330', 'new comment')    # no Issue object required
    comment = jira.add_comment(issue, 'new comment', visibility={'type': 'role', 'value': 'Administrators'})  # for admins only

    comment.update(body = 'updated comment body')
    comment.delete()

### 2.1.7. Transitions

Learn what transitions are available on an issue:

    issue = jira.issue('PROJ-1')
    transitions = jira.transitions(issue)
    [(t['id'], t['name']) for t in transitions]    # [(u'5', u'Resolve Issue'), (u'2', u'Close Issue')]

Note

Only the transitions available to the currently authenticated user will be returned!

Then perform a transition on an issue:

    # Resolve the issue and assign it to 'pm_user' in one step
    jira.transition_issue(issue, '5', assignee={'name': 'pm_user'}, resolution={'id': '3'})

    # The above line is equivalent to:
    jira.transition_issue(issue, '5', fields: {'assignee':{'name': 'pm_user'}, 'resolution':{'id': '3'}})

### 2.1.8. Projects

Projects are objects, just like issues:

    projects = jira.projects()

Also, just like issue objects, project objects are augmented with their fields:

    jra = jira.project('JRA')
    print(jra.name)                 # 'JIRA'
    print(jra.lead.displayName)     # 'Paul Slade [Atlassian]'

It’s no trouble to get the components, versions or roles either (assuming you have permission):

    components = jira.project_components(jra)
    [c.name for c in components]                # 'Accessibility', 'Activity Stream', 'Administration', etc.

    jira.project_roles(jra)                     # 'Administrators', 'Developers', etc.

    versions = jira.project_versions(jra)
    [v.name for v in reversed(versions)]        # '5.1.1', '5.1', '5.0.7', '5.0.6', etc.

### 2.1.9. Watchers

Watchers are objects, represented by `jira.resources.Watchers`:

    watcher = jira.watchers(issue)
    print("Issue has {} watcher(s)".format(watcher.watchCount))
    for watcher in watcher.watchers:
        print(watcher)
        # watcher is instance of jira.resources.User:
        print(watcher.emailAddress)

You can add users to watchers by their name:

    jira.add_watcher(issue, 'username')
    jira.add_watcher(issue, user_resource.name)

And of course you can remove users from watcher:

    jira.remove_watcher(issue, 'username')
    jira.remove_watcher(issue, user_resource.name)

### 2.1.10. Attachments

Attachments let user add files to issues. First you’ll need an issue to which the attachment will be uploaded. Next, you’ll need file itself, that is going to be attachment. File could be file-like object or string, representing path on local machine. Also you can select final name of the attachment if you don’t like original. Here are some examples:

    # upload file from `/some/path/attachment.txt`
    jira.add_attachment(issue=issue, attachment='/some/path/attachment.txt')

    # read and upload a file (note binary mode for opening, it's important):
    with open('/some/path/attachment.txt', 'rb') as f:
        jira.add_attachment(issue=issue, attachment=f)

    # attach file from memory (you can skip IO operations). In this case you MUST provide `filename`.
    import StringIO
    attachment = StringIO.StringIO()
    attachment.write(data)
    jira.add_attachment(issue=issue, attachment=attachment, filename='content.txt')

If you would like to list all available attachment, you can do it with through attachment field:

    for attachment in issue.fields.attachment:
        print("Name: '{filename}', size: {size}".format(
            filename=attachment.filename, size=attachment.size))
        # to read content use `get` method:
        print("Content: '{}'".format(attachment.get()))

You can delete attachment by id:

    # Find issues with attachments:
    query = jira.search_issues(jql_str="attachments is not EMPTY", json_result=True, fields="key, attachment")

    # And remove attachments one by one
    for i in query['issues']:
        for a in i['fields']['attachment']:
            print("For issue {0}, found attach: '{1}' [{2}].".format(i['key'], a['filename'], a['id']))
            jira.delete_attachment(a['id'])