API Documentation¶

endpoint¶

This is an alias to the endpoint class and it has many methods that can be called directly. You can access this classmethod by calling jiraone.endpoint.

from jiraone import LOGIN, endpoint

user = "email"
password = "token"
link = "https://yourinstance.atlassian.net"
LOGIN(user=user, password=password, url=link)

def priorities():
       load = LOGIN.get(endpoint.get_all_priorities())
       if load.status_code == 200:
            # some expression here
            ...

The endpoint gives a base framework for utilising Atlassian API. It does not perform any form of complex data collection or modification. It only applies HTTP requests to retrieve Jira data and returns that data as a response object when combined with jiraone’s request functions. For example, the sample code above shows a typical way these functions can be used. In terms of pagination, you must construct your own to retrieve the data using either a for or while loop depending on what context the information retrieval may be. The API of the endpoint does not produce a payload with all data, rather it will only give a subset of that data and if the retrieval of all data is required, use a loop to get all data.

class jiraone.access.EndPoints¶

A Structural way to dynamically load urls that is fed to other functions.

classmethod add_customers(service_desk_id)¶

Adds one or more customers to a service desk.

If any of the passed customers are associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.

Request POST:
Parameters:: service_desk_id (int) – required
Body param:: usernames, accountIds, datatype -> Array<string>
Returns:: A string of the url
Return type:: str

classmethod add_sd_organization(service_desk_id)¶

This method adds an organization to a service desk.

If the organization ID is already associated with the service desk, no change is made and the resource returns a 204 success code.

Request POST:
Parameters:: service_desk_id (int) – required
Body param:: organizationId, datatype -> integer
Returns:: A string of the url
Return type:: str

classmethod add_users_to_organization(org_id)¶

This method adds users to an organization.

Request POST:
Parameters:: org_id (int) – required
Body param:: usernames, accountIds, datatypes -> Array<string>
Returns:: A string of the url
Return type:: str

classmethod comment(query=None, key_or_id=None, start_at=0, **kwargs)¶

Create, update, delete or get a comment.

Request POST:

Returns a paginated list of just the comments

for a list of comments specified by comment IDs.

Parameters:

query (str | None) – datatype -> string
key_or_id (str | int | None) – datatype -> string required
start_at (int) – datatype -> integer defaults to 0
kwargs (Any) –
Additional arguments

Acceptable options
- max_results: datatype -> integer defaults to 50
  
  query param:
  
  orderBy datatype -> string Valid values: created, -created, +created
- event: defaults to false, set to true to
  
  query param:
  
  expand
  
  body param:
  
  body datatype -> Anything visibility -> The group or role to which this comment is visible. Optional on create and update.
  
  properties datatype -> Array<EntityProperty>
  
  A list of comment properties. Optional on create and update. Additional Properties datatype ->anything
- ids: datatype integers - The ID of the comment.
  
  query param:
  
  expand

Query param:

expand datatype -> string

available options below

renderedBody Returns the comment body rendered in HTML.

properties, returns the comment’s properties.

Body param - ids:

datatype -> Array<integer>

The list of comment IDs. A maximum of 1000 IDs can be specified.

Request GET:

Returns all comments for an issue.

Request POST:

Adds a comment to an issue. key_or_id required

Request GET:

Returns a comment.

Request PUT:

Updates a comment.

key_or_id required ids The ID of the comment.

Request DELETE:

Deletes a comment.

key_or_id required ids required

Returns:

A string of the url

Return type:

str

classmethod create_board()¶

Creates a new board. Board name, type and filter ID is required.

Request GET:

returns a list of boards on the instance that’s accessible by you.

Request POST:

Body param:

name, type, datatype -> string

filterId, datatype -> integer

location, datatype -> object

Returns:

A string of the url

Return type:

str

classmethod create_customer()¶

This method adds a customer to the Jira Service Management.

instance by passing a JSON file including an email address and display name.

Request POST:
Body param:: email, displayName, datatype -> string
Returns:: A string of the url
Return type:: str

classmethod create_organization()¶

This method creates an organization by passing the name of the organization.

Request POST:
Body param:: name, datatype -> string
Returns:: A string of the url
Return type:: str

classmethod create_sprint()¶

Creates a future sprint. Sprint name and origin board id are required. Start date, end date, and goal are optional.

Request POST:
Body param:: name, startDate, endDate, goal, datatype -> string : originBoardId, datatype -> integer
Returns:: A string of the url
Return type:: str

classmethod delete_organization(org_id)¶

This method deletes an organization.

Note that the organization is deleted regardless of other associations it may have. For example, associations with service desks.

Request DELETE:
Parameters:: org_id (int) – required
Returns:: A string of the url
Return type:: str

classmethod delete_sprint(sprint_id)¶

Deletes a sprint.

Once a sprint is deleted, all open issues in the sprint will be moved to the backlog.

Request DELETE:
Parameters:: sprint_id (int) – required
Returns:: A string of the url
Return type:: str

classmethod find_users_with_permission(*args)¶

Find users with permissions to a Project.

Parameters:: args – 1st accountId, 2nd projectKey, 3rd permissions that needs checking all in caps e.g “BROWSE”, “CREATE_ISSUE” etc
Returns:: A string of the url
Return type:: str

classmethod get_all_application_role()¶

Returns all application roles.

In Jira, application roles are managed using the Application access configuration page.

Returns:: A string of the url
Return type:: str

classmethod get_all_issue_security_scheme(level=False, scheme_id=None, level_id=None, attr=False)¶

Returns all issue security schemes or get the security level

Parameters:

level (bool) – Determines if a level is to be checked, then set as true
scheme_id (str | None) – A scheme id used for updating the security level
level_id (str | None) – A level id used for updating the security level
attr (bool) –
Returns the security level is true

Changed in version 0.7.9.

scheme_id - The scheme_id to check for the security schemes

level - The level to be checked

level_id - The id of the level, used for security level update

attr - Returns the security level endpoint

Returns:

A string of the url

Return type:

str

classmethod get_all_issue_type_schemes(query=None, start_at=0, max_results=50, scheme=None)¶

Returns a paginated list of issue type schemes. Only issue type schemes used in classic projects are returned

Parameters:

query (str | None) – A search term
start_at – A row record
max_results – A maximum number to display
scheme (str | None) – create allows POST request to create issue type scheme (the url generated here is basic, so you can add more endpoint depending on the resource you’re trying to reach) and “assign” allows assignment to a specific project

Return type:

str

Changed in version 0.7.9: Scheme - Ability to either create or update an issue type scheme

Returns:

A string of the url

Parameters:

query (str | None)
scheme (str | None)

Return type:

str

classmethod get_all_issue_types()¶

Returns all issue types.

If the user has the Administer Jira global permission, all issue types are returned.

If the user has the “Browse projects” project permission for one or more projects, the issue types associated with the projects the user has permission to browse are returned.

Returns:: A string of the url
Return type:: str

classmethod get_all_permission_scheme(query=None)¶

Returns all permission schemes.

Parameters:: query (str | None) – A search term for this resource.
Returns:: A string of the url
Return type:: str

classmethod get_all_priorities()¶

Returns the list of all issue priorities.

Returns:: A string of the url
Return type:: str

classmethod get_all_quick_filters(board_id, start_at=0, max_results=50)¶

Returns all quick filters from a board, for a given board ID.

Parameters:

board_id (int) – required
start_at (int) – defaults 0
max_results (int) – defaults 50

Returns:

A string of the url

Return type:

str

classmethod get_all_sprints(board_id, query=None, start_at=0, max_results=50)¶

Get all Sprint on a Board.

Parameters:

board_id (int) – A board id
start_at (int) – defaults to 0
max_results (int) – defaults to 50
query (str | None) – A search term. Valid values e.g. future, active, or closed Multiple can be separated by comma e.g. active,closed

Returns:

A string of the url

Return type:

str

classmethod get_board(board_id)¶

Returns the board for the given board ID.

This board will only be returned if the user has permission to view it. Admins without the view permission will see the board as a private one, so will see only a subset of the board’s data (board location for instance).

Parameters:: board_id (int) – A board id
Returns:: A string of the url
Return type:: str

classmethod get_board_by_filter_id(filter_id, start_at=0, max_results=50)¶

Returns any boards which use the provided filter id.

This method can be executed by users without a valid software license in order to find which boards are using a particular filter.

Parameters:

filter_id (int) – required - Filters results to boards that are relevant to a filter. Not supported for the team-managed project boards.
start_at (int) – defaults to 0
max_results (int) – defaults to 50

Returns:

A string of the url

Return type:

str

classmethod get_customers(service_desk_id, start=0, limit=50, query=None)¶

This method returns a list of the customers on a service desk.

The returned list of customers can be filtered using the query parameter. The parameter is matched against customers’ displayName, name, or email. This API is experimental

Parameters:

service_desk_id (int) – required
start (int) – defaults to 0
limit (int) – defaults to 50
query (str | None) – datatype string.

Returns:

A string of the url

Return type:

str

classmethod get_dashboard(dashboard_id)¶

Gets the dashboard.

Parameters:: dashboard_id (int) – An id for the dashboard
Returns:: A string of the url
Return type:: str

classmethod get_field(query=None, start_at=0, max_results=50, system=None)¶

Returns a paginated list of fields for Classic Jira projects. The list can include:

all fields.
specific fields, by defining id.
fields that contain a string in the field name or description,

by defining query.

For example:
query = "type=custom"

specific fields that contain a string in the field name or

description, by defining id and query. Only custom fields can be queried, type must be set to custom.

Find system fields

Fields that cannot be added to the issue navigator are

always returned.

Fields that cannot be placed on an issue screen are always returned.
Fields that depend on global Jira settings are only returned

if the setting is enabled. That is, timetracking fields, subtasks, votes, and watches.

For all other fields, this operation only returns the fields that

the user has permission to view (i.e. The field is use, in at least one project that the user has Browse Projects project permission for.)

Parameters:

query (str | None) – accepted options -> string type=custom (use to search for custom fields)
start_at (int) – defaults to 0
max_results (int) – defaults to 50
system (str | None) –

string accepts any string e.g.
field (use any string to denote as system)

return:

A string of the url

Return type:

str

classmethod get_issues_on_backlog(board_id, query=None, start_at=0, max_results=50)¶

Returns all issues from the board’s backlog, for the given board ID.

This only includes issues that the user has permission to view. The backlog contains incomplete issues that are not assigned to any future or active sprint.

Parameters:

board_id (int) – required
start_at (int) – defaults to 0,
max_results (int) – defaults to 50
query (str | None) –
-> includes other query parameters such as

Query Datatypes

jql | string validateQuery | boolean fields | Array<string> expand | string

Returns:

A string of the url

Return type:

str

classmethod get_issues_on_board(board_id, query=None, start_at=0, max_results=50)¶

Returns all issues from a board, for a given board ID.

This only includes issues that the user has permission to view. An issue belongs to the board if its status is mapped to the board’s column.

Parameters:

board_id (int) – required
start_at (int) – defaults to 0,
max_results (int) – defaults to 50
query (str | None) –
-> includes other query parameters such as

Query Datatypes

jql | string validateQuery | boolean fields | Array<string> expand | string

Returns:

A string of the url

Return type:

str

classmethod get_organization(org_id)¶

This method returns details of an organization.

Use this method to get organization details whenever your application component is passed an organization ID but needs to display other organization details.

Parameters:: org_id (int) – required
Returns:: A string of the url
Return type:: str

classmethod get_organizations(start=0, limit=50, account_id=None)¶

This method returns a list of organizations in the Jira Service Management instance. Use this method when you want to present a list of organizations or want to locate an organization by name.

Parameters:

start (int) – defaults to 0
limit (int) – defaults to 50
account_id (str | None) – datatype string. e.g. 5b10ac8d82e05b22cc7d4ef5

Returns:

A string of the url

Return type:

str

classmethod get_project_component(ids=None, id_or_key=None, move_to=None, **kwargs)¶

Returns all components in a project. See the Get project components paginated resource if you want to get a full list of components with pagination. The project ID or project key (case-sensitive).

Parameters:

ids (str | None) – A component id (required for GET, PUT, DEL)
id_or_key (str | int | None) – An issue key or id
move_to (str | None) – An id of a component to replace
kwargs (Any) –
Any additional arguments to pass

Acceptable options
- issue_count: Count issues of a component
- pagination: Allows project component pagination.
  For pagination argument, you can combine the query argument to get more details.
- query: A query parameter for pagination argument.
  e.g. startAt=0&maxResults=50

Request POST:

Creates a component. Use components to provide containers: for issues within a project.

body param:

assignee - Datatype (User) - denoting a user object
assigneeType - Datatype (str)
description - Datatype (str)
id - Datatype(str)
isAssigneeTypeValid - Datatype (bool)
lead - Datatype (User) - denoting a user object
leadAccountId - Datatype (str)
leadUserName - Datatype (str)
name - Datatype (str)
project - Datatype (str)
projectId - Datatype (int)
realAssignee - Datatype (User)
realAssigneeType - Datatype (str)
self - Datatype (str)

Example:

body = {
   "assigneeType": "PROJECT_LEAD",
   "description": "This is a Jira component",
   "isAssigneeTypeValid": false,
   "leadAccountId": "5b10a2844cxxxxxx700ede21g",
   "name": "Component 1",
   "project": "BAC"
  }

Request GET:

Returns a component.This operation can be accessed anonymously.

Request PUT:

Updates a component. Any fields included in: the request are overwritten

body param:

assignee - Datatype (User) - denoting a user object
assigneeType - Datatype (str)
description - Datatype (str)
id - Datatype(str)
isAssigneeTypeValid - Datatype (bool)
lead - Datatype (User) - denoting a user object
leadAccountId - Datatype (str)
leadUserName - Datatype (str)
name - Datatype (str)
project - Datatype (str)
projectId - Datatype (int)
realAssignee - Datatype (User)
realAssigneeType - Datatype (str)
self - Datatype (str)

Request DELETE:

Deletes a component. :query param: moveIssuesTo

Returns:

A string of the url

Return type:

str

classmethod get_project_role(*args)¶

Returns a project role’s details and actors associated with the project.

Parameters:: args – projectKey or id or the Project id of the role
Returns:: A string of the url
Return type:: str

classmethod get_project_versions(ids=None, id_or_key=None, move=False, **kwargs)¶

Returns all versions in a project. See the Get project version paginated. Resource if you want to get a full list of versions without pagination.

Parameters:

ids (str | None) – A version id (required for GET, PUT, POST)
id_or_key (str | int | None) – An issue key or id
move (bool) – Modifies the version’s sequence within the project
kwargs (Any) –
Additional keyword arguments to provide

Acceptable options
- move_to_issue: The ID of the version to merge into.
- swap: Deletes a project version. Used with POST method
- issue_count: Count issues of a version. Used with
  GET method
- unresolved_count: Count of a version’s unresolved
  issues.Used with “GET” method
- pagination: Allows project version pagination
- query: A query parameter for pagination argument.
  e.g. startAt=0&maxResults=50

Request POST:

Creates a version.

body param:

archived - Datatype (bool)
expand - Datatype (str)
description - Datatype (str)
id - Datatype(str)
issueStatusForFixVersion - Datatype (VersionIssueStatus)
moveUnfixIssuesTo - Datatype (str)
name - Datatype (str)
operations - Datatype (list)
overdue - Datatype (bool)
project - Datatype (str)
projectId - Datatype (int)
releaseDate - Datatype (str)
release - Datatype (bool)
startDate - Datatype (str)
userReleaseDate - Datatype (str)
userStateDate - Datatype (str)
self - Datatype (str)

Example:

body = {
 "archived": false,
 "description": "An excellent version",
  "name": "New Version 1",
 "projectId": 10000,
 "releaseDate": "2010-07-06",
"released": true
}

Request GET:

Returns all versions in a project.This operation can be: accessed anonymously. You can either use a return of all version or use the pagination argument for a paginated list of all versions. Project key required

query param:

Used for query argument in pagination: The query argument is a string and can be constructed as below.

Example:

query = “startAt=0&maxResults=50&orderBy=description,name&status=released &expand=issuestatus”

Request PUT:

Updates a version. An id must be supplied

body param:

archived - Datatype (bool)
expand - Datatype (str)
description - Datatype (str)
id - Datatype(str)
issueStatusForFixVersion - Datatype (VersionIssueStatus)
moveUnfixIssuesTo - Datatype (str)
name - Datatype (str)
operations - Datatype (list)
overdue - Datatype (bool)
project - Datatype (str)
projectId - Datatype (int)
releaseDate - Datatype (str)
release - Datatype (bool)
startDate - Datatype (str)
userReleaseDate - Datatype (str)
userStateDate - Datatype (str)
self - Datatype (str)

Request POST:

Deletes a version.

body param:

Used with delete and replace version

customFieldReplacementList - Datatype (list)
moveAffectedIssuesTo - Datatype (int)
moveFixedIssuesTo - Datatype (int)

Example:

body = {
      "customFieldReplacementList": [
             {
         "customFieldId": 66,
        "moveTo": 67
            }
                 ],
           "moveAffectedIssuesTo": 97,
          "moveFixIssuesTo": 92
           }

body param:

Moves a version

after - Datatype (str)
position - - Datatype (str)

Returns:

A string of the url

classmethod get_projects(*args, start_at=0, max_results=50)¶

Return a list of Projects available on an Instance How to use this endpoint /rest/api/3/project/search is mentioned here

param args:

Query Parameters that are useful mostly.

query, example: query=key,name {caseInsensitive}

searchBy, example: searchBy=key,name

action, example: action=browse

available options [view, browse, edit]

status example: status=live

available options [live, archived, deleted]

e). expand, example: expand=insight

available options [insight, description, projectKeys, url, issueTypes, lead]

param start_at:

defaults as keyword args,example startAt=0

param max_results:

defaults as keyword args, example maxResults=50

return:

A string of the url

Parameters:

args (Any)
start_at (int)
max_results (int)

Return type:

str

classmethod get_projects_on_board(board_id, start_at=0, max_results=50)¶

Returns all projects that are associated with the board, for the given board ID.

If the user does not have permission to view the board, no projects will be returned at all. Returned projects are ordered by the name.

Parameters:

board_id (int) – required
start_at (int) – defaults 0
max_results (int) – defaults 50

Returns:

A string of the url

Return type:

str

classmethod get_quick_filter(board_id, quick_filter_id)¶

Returns the quick filter for a given quick filter ID.

The quick filter will only be returned if the user can view the board that the quick filter belongs to.

Parameters:

board_id (int) – required,
quick_filter_id (int) – required

Returns:

A string of the url

Return type:

str

classmethod get_resolutions()¶

Returns a list of all issue resolution values. :return: A string of the url

Return type:: str

classmethod get_roles_for_project(id_or_key)¶

Returns a list of project roles for the project returning the name and self URL for each role.

Parameters:: id_or_key (str | int) – An issue key or id
Returns:: A string of the url
Return type:: str

classmethod get_sd_by_id(service_desk_id)¶

This method returns a service desk. Use this method to get service desk details whenever your application component is passed a service desk ID but needs to display other service desk details.

Parameters:: service_desk_id (int) – The ID of the service desk to return. Required
Returns:: string
Return type:: str

classmethod get_sd_organizations(service_desk_id, start=0, limit=50, account_id=None)¶

This method returns a list of all organizations associated with a service desk.

Parameters:

service_desk_id (int) – required
start (int) – defaults to 0
limit (int) – defaults to 50
account_id (str | None) – datatype string. e.g. 5b10ac8d82e05b22cc7d4ef5

Returns:

A string of the url

Return type:

str

classmethod get_server_info()¶

This method retrieves information about the Jira Service Management.

instance such as software version, builds, and related links.

Returns:: A string of the url
Return type:: str

classmethod get_service_desks(start=0, limit=100)¶

This method returns all the service desks in the Jira Service Management instance that the user has permission to access. Use this method where you need a list of service desks or need to locate a service desk by name or keyword.

Parameters:

start (int) – integer - pagination row
limit (int) – integer - limit to each pagination

Returns:

string

Return type:

str

classmethod get_sprint(sprint_id)¶

Returns the sprint for a given sprint ID.

The sprint will only be returned if the user can view the board that the sprint was created on, or view at least one of the issues in the sprint.

Parameters:: sprint_id (int) – required
Returns:: A string of the url
Return type:: str

classmethod get_user_group(account_id)¶

Search for the groups a user belongs to

Parameters:: account_id (str) – An alphanumeric required string
Returns:: A string of the url
Return type:: str

classmethod get_users_in_organization(org_id, start=0, limit=50)¶

This method returns all the users associated with an organization.

Use this method where you want to provide a list of users for an organization or determine if a user is associated with an organization.

Parameters:

org_id (int) – required
start (int) – datatype integer
limit (int) – datatype integer

Returns:

A string of the url

Return type:

str

classmethod group_jira_users(group_name, account_id=None)¶

Used for addition and removal of users to and from groups.

request POST:

Adds a user to a group.

query param:

groupname required, datatype -> string

body param:

name, accountId, datatype -> string returns 201 if successful

request DELETE:

Removes a user from a group.

query param:

group_name required, account_id required, datatype -> string returns 200 if successful

Parameters:

group_name (str) – name of group
account_id (str | None) –
string of a user account

return:

A string of the url

Return type:

str

classmethod instance_info()¶: Returns licensing information about the Jira instance.

classmethod issue_attachments(id_or_key=None, attach_id=None, uri=None, query=None)¶

Returns the attachment content.

request GET:

Get Jira attachment settings

Returns the attachment settings, that is, whether attachments. are enabled and the maximum attachment size allowed.

request GET:

Get attachment metadata

Returns the metadata for an attachment. Note that the attachment itself is not returned.

param attach_id:

required (id of the attachment), datatype -> string

request DELETE:

Deletes an attachment from an issue.

attach_id required (id of the attachment), datatype -> string.

Request GET:

Get all metadata for an expanded attachment.

Parameters:

query (str | None) –
This argument accepts a string, check the options.

available options
- expand/human - Returns the metadata for the contents of an
  attachment, if it is an archive, and metadata for the attachment itself. For example, if the attachment is a ZIP archive, then information about the files in the archive is returned and metadata for the ZIP archive.
- expand/raw - Returns the metadata for the contents of an
  attachment, if it is an archive. For example, if the attachment is a ZIP archive, then information about the files in the archive is returned. Currently, only the ZIP archive format is supported.
id_or_key (str | None)
attach_id (str | None)
uri (str | None)

Request POST:

Adds one or more attachments to an issue.
Attachments are posted as multipart/form-data.

request POST:

Adds one or more attachments to an issue.

Attachments are posted as multipart/form-data.

param id_or_key:

(required) The ID or key of the issue that are added to and attachments.

param uri:

various endpoint to attachment.

return:

A string of the url

Return type:

str

classmethod issue_export(query=None, start=0, limit=1000, fields='all')¶

Generate an export of Jira issues using a JQL.

Parameters:

query (str | None) – A JQL of the issues to be exported
start (int) – A start counter
limit (int) – Max limit allowed for export
fields (str) – Determine if export is current fields or all fields.

Return type:

str

Changed in version 0.7.6.

fields - added a keyword argument for transition between current and all: fields

query - Renamed “url” parameter into “query” for better clarity of names.

Returns:

A string of the export URL

Parameters:

query (str | None)
start (int)
limit (int)
fields (str)

Return type:

str

classmethod issue_link(link_id=None)¶

Use this operation to indicate a relationship between two issues and optionally add a comment to the (outward) issue.

Request GET:: Returns an issue link.
Request POST:: Creates a link between two issues. link_id required.
Request DELETE:: Deletes an issue link. link_id required.
Parameters:: link_id (str | None) – The ID of the issue link.
Returns:: str
Return type:: str

classmethod issue_link_types(link_type_id=None)¶

Returns a list of all issue link types.

Request GET:

To use this operation, the site must have issue linking enabled.

Request GET:

Get issue link types, this requires the linked type id.

Request POST:

Creates an issue link type. Use this: operation to create descriptions of the reasons why issues are linked.

body param:

id - Datatype (str)
inward - Datatype (str)
name - Datatype (str)
outward - Datatype (str)
self - Datatype (str)

Example:

payload = {
        "inward": "Duplicated by",
        "name": "Duplicate",
        "outward": "Duplicates"
         }

Request DELETE:

Deletes an issue link type. This requires the linked type id

Request PUT:

Updates an issue link type.

This requires the linked type id

body param:

id - Datatype (str)
inward - Datatype (str)
name - Datatype (str)
outward - Datatype (str)
self - Datatype (str)

Example:

payload = {
        "inward": "Duplicated by",
        "name": "Duplicate",
        "outward": "Duplicates"
         }

Parameters:

link_type_id (str | None) – The link type id

Returns:

Return type:

str

classmethod issue_votes(key_or_id=None)¶

Return the number of votes on an issue

Request GET:: Returns details about the votes on an issue.
Request POST:: Adds the user’s vote to an issue.
Request DELETE:: Deletes a user’s vote from an issue.
Parameters:: key_or_id (str | int | None) – The ID or key of the issue.
Returns:: str
Return type:: str

classmethod issue_watchers(key_or_id=None, account_id=None)¶

This operation requires the Allow users to watch issues option to be ON.

Request GET:

Returns the watchers for an issue.

Request POST:

Adds a user as a watcher of an issue by passing the account ID of the user.

Request DELETE:

Deletes a user as a watcher of an issue.

Parameters:

key_or_id (str | int | None) – The ID or key of the issue.
account_id (str | None) – The account ID of the user

Request POST:

Returns, for the user, details of the: watched status of issues from a list.

body param:: issueIds - List[int]

Returns:

str

Return type:

str

classmethod issues(issue_key_or_id=None, query=None, uri=None, event=False)¶

Creates issues, delete issues, bulk create issue, transitions.

A transition may be applied, to move the issue or subtask to a workflow step other than the default start step, and issue properties set.

Request POST:

Creates an issue or, where the option to

create subtasks is enabled in Jira, a subtask.

Parameters:

uri (str | None) –
available options [bulk, createmeta]
- e.g. endpoint: /rest/api/3/issue/bulk
- e.g. endpoint /rest/api/3/issue/createmeta
query (Any | None) –

Use the query keyword argument
and structure a parameter
- e.g. query=”notifyUsers=false”
OR in the case of changelog the endpoint of “changelog” /rest/api/3/issue/{issueIdOrKey}/changelog
event (bool) –
datatype -> boolean
- determine if you can get a changelog from the issue.
default is false. if True required parameters are:
issue_key_or_id (str | int | None)
issue_key_or_id – -> The body parameter has to be a bundled data that should be posted to the desired endpoint.

Query param:

updateHistory, datatype -> boolean

Body param:

transition, fields, update, historyMetadata, datatype -> object : properties, datatype -> Array<EntityProperty> : Additional Properties, datatype -> Any

Request POST:

Bulk create issue Creates an issues and, where the option to create subtasks is enabled in Jira, subtasks.

Body param:

issueUpdates, datatype -> Array<IssueUpdateDetails> : Additional Properties, datatype -> Any

Request GET:

Create issue metadata

Returns a details of projects, issue types within projects, and, when requested, the create screen fields for each issue type for the user.

Query param:

projectIds, projectKeys, issuetypeIds, issuetypeNames,: datatype -> Array<string>

: expand, datatype -> string

Request GET:

Get issue. Return the details of an issue

Example:

endpoint /rest/api/3/issue/{issueIdOrKey}

Query param:

issue_key_or_id required fields, properties, datatype -> Array<string> fieldsByKeys, updateHistory, datatype -> boolean expand, datatype -> string

Request PUT:

Edits an issue. A transition may be applied

and issue properties updated as part of the edit.

Example:

endpoint /rest/api/3/issue/{issueIdOrKey}

Query param:

issue_key_or_id required : notifyUsers, overrideScreenSecurity, overrideEditableFlag, datatype -> boolean

Body param:

transition, fields, update, historyMetadata,: properties, Additional Properties,

datatype -> object

Request DELETE:

Deletes an issue.

Example:

endpoint /rest/api/3/issue/{issueIdOrKey}

Query param:

issue_key_or_id required : deleteSubtasks, datatype -> string, values = (true | false)

Returns:

A string of the url

Return type:

str

classmethod jira_group(group_name=None, swap_group=None)¶

Used for Creation and deletion of Jira groups.

Request POST:

Creates a group.

body param:: name required, datatype -> string returns 201 if successful

Request DELETE:

Deletes a group.

The group to transfer restrictions to. Only comments and worklogs are transferred. If restrictions are not transferred, comments and worklogs are inaccessible after the deletion.

query param:: group_name required, swap_group, datatype -> string returns 200 if successful

Parameters:

group_name (str | None) – name of group
swap_group (str | None) – group name to swap

Returns:

A string of the url

Return type:

str

classmethod jira_user(account_id=None)¶

API for User creation, deletion and retrieval.

Request POST:

Creates a user. This resource is retained for

legacy compatibility. As soon as a more suitable alternative is available this resource will be deprecated

Body param:

key, name, password, emailAddress, displayName,: notification, datatypes -> string

: applicationKeys, datatype -> Array<string> : Additional Properties, datatypes -> Any

returns 201 for successful creation

Request DELETE:

Deletes a user.

Body param:

accountId, datatype -> string required returns 204 for successful deletion

Request GET:

Returns a user.

Body param:

accountId, expand, datatypes -> string

Parameters:

account_id (str | None) –

string for a user account

Returns:

A string of the url

Return type:

str

classmethod move_issues_to_backlog()¶

Move issues to the backlog. This operation is equivalent to remove future and active sprints from a given set of issues. At most 50 issues may be moved at once.

Request POST:
Body param:: issues, datatype -> Array<string>
Return type:: str

Send a POST request within API.

Returns:: A string of the url
Return type:: str

classmethod move_issues_to_backlog_from_board(board_id)¶

Move issues to the backlog of a particular board (if they are already on that board).

This operation is equivalent to remove future and active sprints from a given set of issues if the board has sprints If the board does not have sprints this will put the issues back into the backlog from the board. At most 50 issues may be moved at once.

Request POST:

Parameters:

board_id (int) – required

Body param:

issues, datatype -> Array<string>,

rankBeforeIssue, rankAfterIssue, type -> string

rankCustomFieldId, type -> integer

Returns:

A string of the url

Return type:

str

classmethod move_issues_to_board(board_id)¶

Move issues from the backog to the board (if they are already in the backlog of that board).

This operation either moves an issue(s) onto a board from the backlog (by adding it to the issueList for the board) Or transitions the issue(s) to the first column for a kanban board with backlog.

Request POST:
Parameters:: board_id (int) – required
Body param:: rankBeforeIssue, rankAfterIssue, datatype -> string : rankCustomFieldId, datatype -> integer : issues, datatype -> Array<string>
Returns:: A string of the url
Return type:: str

classmethod myself()¶

Return data on your own user.

Returns:: A string of the url
Return type:: str

classmethod project_avatar(key_or_id=None, avatar_id=None, method='get', **kwargs)¶

Performs multiple operations to the avatar displayed for a project.

Request PUT:

Set the avatar to a project, the project key or id is required and the avatar_id needs to be passed in the body

Parameters:

key_or_id (str | int | None)
avatar_id (str | None)
method (str | None)

Return type:

str

Example 1:

payload = {"id": "10010"}

Request DELETE:

Deletes a custom avatar from a project. Note that system avatars cannot be deleted.

Request POST:

Loads an avatar for a project. Specify the avatar’s local file location in the body of the request

Parameters:

key_or_id (str | int | None)
avatar_id (str | None)
method (str | None)

Return type:

str

Example 2:

X-Atlassian-Token: no-check
Content-Type: image/image type Valid image types are JPEG, GIF, or PNG.

Request GET:

Returns all project avatars, grouped by system and custom avatars.

Parameters:

key_or_id (str | int | None) – Required project key or id
avatar_id (str | None) – Required Avatar id if method argument is a DELETE or PUT request
method (str | None) – Define an HTTP method of operation options: get, put, post, delete
kwargs –

Additional query parameters. The below
variables all are in integers
- cord_x: The X coordinate of the top-left corner of the
  crop region.
- cord_y: The Y coordinate of the top-left corner of the
  crop region.
- size: The length of each side of the crop region.
  e.g. 16, 24, 32, and 48
  
  The cropped image is then used to create avatars of 16x16, 4x24, 32x32, and 48x48 in size.

Returns:

string

Return type:

str

classmethod project_role(attr=None, key_or_id=None, role_id=None)¶

Performs multiple functions for project role from creation to setting of actors on projects.

Creates a new project role with no default actors if attr is None
Adds, update and delete actors to a project role for the project attr argument must be True to access this function Accepts HTTP method “PUT, POST, DELETE”.
Returns the default actors for the project role. attr argument must be False

Parameters:

attr (bool | None) – True if adding project role actors to a project. False if removing project role actors from a project. None creates the project role
key_or_id (str | int | None) – The project key or id to assign a role
role_id (int | None) – The id of the project role when assigning actors to a project

Returns:

string

Return type:

str

classmethod project_validate(key_or_name, check=None)¶

Validates a project key by confirming the key is a valid string and not in use. If checking for project key or name, and it is in use, an auto generated project key or name is returned

When the project does not exist, the below result is gotten.

Example 1:

{"errorMessages":[],"errors":{}}

When the project exist, the below result is gotten

Example 2:

{"errorMessages":[],"errors":{"projectKey":
"Project 'Test Project 1' uses this project key."}}

Parameters:

key_or_name (str) – A project key to search or name when check argument is not None
check (str | None) –
Validates a project key or name

options * key * name

Returns:

A string

Return type:

str

classmethod projects(id_or_key=None, query=None, uri=None, enable_undo=None)¶

Create, delete, update, archive, get status.

request POST:

for project creations.

The project types are available according to the installed Jira features as follows

param id_or_key:

required

param uri:

optional for accessing other project
endpoints -> string

Example:

endpoint: /rest/api/3/project/{projectIdOrKey}/{archive}

available options [archive, delete, restore, statuses]

archive - Archives a project. Archived

projects cannot be deleted.

delete - Deletes a project asynchronously.

restore - Restores a project from the

Jira recycle bin.

statuses - Returns the valid statuses

for a project.

body param:

projectTypeKey and projectTemplateKey required
for creation, datatype -> string

: name, key, description, leadAccountId, url,
assigneeType, datatype -> string

: avatarId, issueSecurityScheme, permissionScheme,
notificationScheme, categoryId, datatype -> integer

request GET:

Returns the project details for a project.

This operation can be accessed anonymously.

query param:

expand, datatype -> string
properties, datatype -> Array<string>

request PUT:

Updates the project details for a project.

param query:

expand, datatype -> string

body param:

datatype -> string : name, key, description, leadAccountId, url,

assigneeType, datatype -> string

: avatarId, issueSecurityScheme, permissionScheme,
notificationScheme, categoryId, datatype -> integer

request DELETE:

Deletes a project.

param enable_undo:

datatype -> boolean

return:

A string of the url

Parameters:

id_or_key (str | int | None)
query (str | None)
uri (str | None)
enable_undo (bool | None)

Return type:

str

classmethod remote_links(key_or_id=None, link_id=None)¶

Returns the remote issue links for an issue. When a remote issue link global ID is provided the record with that global ID is returned.

When using PUT and POST method, the body parameter are similar and the object body parameter is required.

When using the DELETE method, you can delete remote issue link by globalId or, you can delete by id

Request GET:

Gets the remote link

Parameters:

key_or_id (str | None) –
The ID or key of the issue. :body param: globalId - datatype(str)

The global ID of the remote issue link.
link_id (str | None) – The ID of the remote issue link.

Request POST:

Create or update remote link.

Body param:

globalId - datatype(str): The global ID of the remote issue link.

application - datatype(dict) Details of the remote application the linked item is in. For example, trello. relationship - datatype(str) Description of the relationship between the issue and the linked item. object - datatype(dict) Details of the item linked to.

Request DELETE:

Deletes the remote issue link from the issue using the link’s global ID.

Request PUT:

Updates a remote issue link for an issue.

Returns:

A string construct of the url

Return type:

str

classmethod remove_customers(service_desk_id)¶

This method removes one or more customers from a service desk.

The service desk must have closed access. If any of the passed customers are not associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.

Request DELETE:
Parameters:: service_desk_id (int) – required
Body param:: usernames, accountIds, datatype -> Array<string>
Returns:: A string of the url
Return type:: str

classmethod remove_sd_organization(service_desk_id)¶

This method removes an organization from a service desk.

If the organization ID does not match an organization associated with the service desk, no change is made and the resource returns a 204 success code.

Request DELETE:
Parameters:: service_desk_id (int) – required
Body param:: organizationId, datatype -> integer
Returns:: A string of the url
Return type:: str

classmethod remove_users_from_organization(org_id)¶

This method removes users from an organization.

Request DELETE:
Parameters:: org_id (int) – required
Body param:: usernames, accountIds, datatypes -> Array<string>
Returns:: A string of the url
Return type:: str

classmethod runbackup()¶

Runs a backup process for the environment

Example 1:: # send a POST request with the payload payload_data = {“cbAttachments”: “false”, “exportToCloud”: “true”} # changing “cbAttachments” to “true” will enable backup with attachments

classmethod search_all_notification_schemes(query=None, start_at=0, max_results=50, attr=False)¶

Returns a paginated list of notification schemes ordered by display name.

Parameters:

query (str | None) – 1st String value for expand= {all, field, group, user, projectRole, notificationSchemeEvents}
start_at – has default value of 0
max_results – has default value of 50
attr (bool) – A bool value

Return type:

str

Changed in version 0.7.9.

attr - An indicator to switch endpoint

Returns:

A string of the url

Parameters:

query (str | None)
attr (bool)

Return type:

str

classmethod search_all_screens(query=0)¶

Returns a paginated list of all screens or those specified by one or more screen IDs.

Parameters:: query (int) – has default value of 0
Return type:: str

maxResults=100 (default)

Returns:: A string of the url
Parameters:: query (int)
Return type:: str

classmethod search_all_workflow_schemes(query=0)¶

Returns a paginated list of all workflow schemes, not including draft workflow schemes.

Parameters:

query (int) –

has default value of 0

filled - maxResults=50 (default)

Returns:

A string of the url

Return type:

str

classmethod search_all_workflows(query=0)¶

Returns a paginated list of published classic workflows. When workflow names are specified.

details of those workflows are returned. Otherwise, all published classic workflows are returned. This operation does not return next-gen workflows.

Parameters:

query (int) –

has default value of 0

filled - maxResults=50 (default)

Returns:

A string of the url

Return type:

str

classmethod search_for_dashboard(query=None, start_at=0)¶

Returns a paginated list of dashboards. This operation is similar to

Get dashboards except that the results can be refined to include dashboards that have specific attributes. For example, dashboards with a particular name. When multiple attributes are specified only filters matching all attributes are returned.

Parameters:

query (str | None) – 1st String value dashboardName, accountId, owner, groupname, projectId
start_at (int) – has default value of 0

Param:

filled: - maxResult=20 (default)

Returns:

A string of the url

Return type:

str

classmethod search_for_filters(query=None, start_at=0)¶

Returns a paginated list of filters. Use this operation to get:

specific filters, by defining id only.
filters that match all the specified attributes. For example, all filters

for a user with a particular word in their name. When multiple attributes are specified only filters matching all attributes are returned.

Parameters:

query (str | None) – 1st String value filterName, accountId, owner, groupname, projectId
start_at (int) – has default value of 0

Param:

filled: - maxResults=50 (default)

Returns:

A string of the url

Return type:

str

classmethod search_for_screen_schemes(query=0)¶

Returns a paginated list of screen schemes.

Only screen schemes used in classic projects are returned.

Parameters:: query (int) – has default value of 0
Return type:: str

maxResults=25 (default)

Returns:: A string of the url
Parameters:: query (int)
Return type:: str

classmethod search_issues_jql(query, start_at=0, max_results=50)¶

Searches for issues using JQL.

Parameters:

query (str) – A search term.
start_at (int) – A record start row
max_results (int) – A max result to return

Returns:

A string of the url

Return type:

str

classmethod search_users(start_at=0, max_result=50, default=False)¶

Search multiple users and retrieve the data

Parameters:

start_at (int) – An integer record row
max_result (int) – An integer of max capacity
default (bool) – Changes context between default user search

Return type:

str

and all search

Returns:

A string of the url

Parameters:

start_at (int)
max_result (int)
default (bool)

Return type:

str

classmethod server_info()¶

Returns information about the Jira instance. This operation can be accessed anonymously.

Returns:: strings
Return type:: str

classmethod task(task_id=None, method='GET')¶

When a task has finished, this operation returns the JSON blob applicable to the task

Request GET:

Returns the status of a long-running asynchronous task.

Request POST:

Cancels a task.

Parameters:

task_id (str | None) – The ID of the task.
method (str | None) – An HTTP request type

Returns:

str

Return type:

str

classmethod update_sprint(sprint_id)¶

Performs a full update of a sprint.

A full update means that the result will be exactly the same as the request body. Any fields not present in the request JSON will be set to null.

Request PUT:

Parameters:

sprint_id (int) – required

Body param:

name, state, startDate, endDate, goal, self (format: uri),: completeDate, datatype -> string

: id, originBoardId, datatype -> integer

Returns:

A string of the url

Return type:

str

classmethod webhooks(uri=None)¶

Makes a call to the webhook API. Only connect app or OAuth 2.0 can use this connection.

Request GET:

Returns a paginated list of the webhooks registered by the calling app.

Request POST:

Registers webhooks.

Request DELETE:

Removes webhooks by ID. :body param: webhookIds - required List[int]

Parameters:

uri (str | None) –

Url path context

options available

failed - Returns webhooks that have recently
failed
refresh - Extends the life of webhook.

Request GET:

After 72 hours the failure may no longer be returned by this operation.

Request PUT:

Webhooks registered through the REST API expire after 30 days

Returns:

str

Return type:

str

classmethod work_logs(key_or_id=None, start_at=0, max_results=1048576, **kwargs)¶

Returns worklogs for an issue, starting from the oldest worklog or from the worklog started on or after a date and time.

Request GET:

Returns worklogs for an issue

Request GET:

Returns a worklog. When a worklog_id is specified

Parameters:

key_or_id (str | int | None) – The ID or key of the issue.
start_at (int) – The index of the first item to return in a page of results (page offset).
max_results (int) – The maximum number of items to return per page.
kwargs (Any) –
Additional keyword

Acceptable options
- started_after: The worklog start date and time, as a
  UNIX timestamp in milliseconds, after which worklogs are returned.
- started_before: The worklog start date and time, as a
  UNIX timestamp in milliseconds, before which worklogs are returned.
- worklog_id: The ID of the worklog.
- expand: Use expand to include additional information
  about worklogs in the response.
- notify_users: Whether users watching the issue are
  notified by email.
- adjust_estimate: Defines how to update the issue’s
  time estimate, the options are new Sets the estimate to a specific value, defined in newEstimate. leave Leaves the estimate unchanged. auto Updates the estimate by the difference between the original and updated value of timeSpent or timeSpentSeconds. Valid values: new, leave, manual, auto
- new_estimate: The value to set as the issue’s remaining
  time estimate, as days (#d), hours (#h), or minutes (#m or #). For example, 2d. Required when adjustEstimate is new.
- override_editable_flag: Whether the worklog should be
  added to the issue even if the issue is not editable.
- increase_by: The amount to increase the issue’s
  remaining estimate by, as days (#d), hours (#h), or minutes (#m or #).
  
  For example, 2d.
- reduce_by: The amount to reduce the issue’s remaining
  estimate by, as days (#d), hours (#h), or minutes (#m). For example, 2d.
- since: The date and time, as a UNIX timestamp in
  milliseconds, after which updated worklogs are returned.

Request POST:

Adds a worklog to an issue. Other query parameters can be specified such as adjust_estimate argument.

Request PUT:

Updates a worklog. When a worklog_id is specified

Request DELETE:

Deletes a worklog from an issue. When a worklog_id is specified. Other query parameters can be specified such as adjust_estimate argument.

Returns:

str

Return type:

str

classmethod worklog_properties(key_or_id=None, worklog_id=None, property_key=None)¶

Returns the worklog properties of an issue

Request GET:

Returns the keys of all properties for a worklog.

Parameters:

key_or_id (str | int | None) – The ID or key of the issue.
worklog_id (str | None) – The ID of the worklog.
property_key (str | None) – The key of the property.

Request GET:

Returns the value of a worklog property.

Request PUT:

Sets the value of a worklog property.

body param:: The request body can contain any valid application/json.

Request DELETE:

Deletes a worklog property.

Returns:

str

Return type:

str

LOGIN¶

This is a call to the LOGIN class. The way to use this class is to make a call to LOGIN

from jiraone import LOGIN

user = "email"
password = "token"
link = "https://yourinstance.atlassian.net"
LOGIN(user=user, password=password, url=link)

Once a login session starts, you can join other classes and make a call directly to other objects.

from jiraone import LOGIN, endpoint

# previous login statement
LOGIN.get(endpoint.myself())

class jiraone.access.Credentials(user, password, url=None, oauth=None, session=None)¶

class.Credentials -> used for authentication of the user to the Instance.

Parameters:

user (str)
password (str)
url (str)
oauth (dict)
session (Any)

custom_method(*args, **kwargs)¶

A custom request to HTTP request.

import jiraone
# previous login expression
req = jiraone.LOGIN.custom_method('GET', 'https://nexusfive.atlassian.net')
print(req)
# <Response [200]>

Parameters:

args –
The HTTP method type e.g. PUT, PATCH, DELETE etc

Also, includes the URL that needs to be queried.
kwargs –
Additional keyword arguments to requests module

For example:
```
json={"file": content}
data={"file": content}
```

Returns:

An HTTP response

Return type:

Response

delete(url, **kwargs)¶

A delete request to HTTP request.

Parameters:

url (str) – A valid URL
kwargs – Additional keyword arguments to requests module

Returns:

An HTTP response

Return type:

Response

static from_jira(obj)¶

Performs a login initialization from a JIRA object. The authentication, looks into basic auth from the jira python package. It returns the same JIRA object after authentication happens, so you can easily access all the authenticated instances of both jira and jiraone packages.

Example 1:

from jira import JIRA
from jiraone import LOGIN, endpoint

my_jira = JIRA(server="https://nexusfive.atlassian.net",
        basic_auth=("prince@example.com",
        "MXKSlsXXXXX"))
LOGIN.from_jira(my_jira)
print(LOGIN.get(endpoint.myself()))
# response
# <Response [200]>

You can assign a variable to the jiraone LOGIN.from_jira() and continue to use both jira and jiraone packages simultaneously.

Example 2:

from jira import JIRA
from jiraone import LOGIN, PROJECT

jiras = JIRA(server="https://nexusfive.atlassian.net",
        basic_auth=("prince@example.com",
        "MXKSlsXXXXX"))
my_jira = LOGIN.from_jira(jiras)
# Making a request to JIRA's methods
print(my_jira.myself())
# response
# {'self': 'https://example.atlassian.net/rest/api/2/user?
#            accountId=557058:xxx',
#           'accountId': '557058:xxx'}
# Making a request to jiraone's methods
jql = "project = CT ORDER BY Created DESC"
print(PROJECT.issue_count(jql))
# response
# {'count': 18230, 'max_page': 18}

Parameters:: obj (Any) – A call to a JIRA Interface
Returns:: JIRA object
Return type:: Any

get(url, *args, payload=None, **kwargs)¶

A get request to HTTP request.

Parameters:

url (str) – A valid URL
args – Additional arguments if any
payload (dict | None) – A JSON data representation
kwargs – Additional keyword arguments to requests module

Returns:

An HTTP response

Return type:

Response

oauth_session(oauth)¶

A session initializer to HTTP request using OAuth.

This method implements the Atlassian OAuth 2.0 3LO implementation. To reissue token, this method uses a refresh token session. This is possible, if the scope in the ``callback_url contains offline_access.

client = {
    "client_id": "JixkXXX",
    "client_secret": "KmnlXXXX",
    "name": "nexusfive",
    "callback_url": "https://auth.atlassian.com/XXXXX"
}

A typical client object should look like the above. Which is passed to the LOGIN initializer as below. The name key is needed to specifically target an instance, but it is optional if you have multiple instances that your app is connected to. The client_id, client_secret and callback_url are mandatory.

from jiraone import LOGIN

# previous expression
LOGIN(oauth=client)

To store and reuse the oauth token, you will need to call the property value. This object is a string which can be stored to a database and pulled as a variable.

#  Example for storing the OAuth token
dumps = LOGIN.save_oauth # this is a property value which contains a
# dict of tokens in strings
# As long as a handshake has been allowed with OAuth,
# the above should exist.
LOGIN.save_oauth = f"{json.dumps(dumps)}"
# with the above string, you can easily save your
# OAuth tokens into a DB or file.
# Please note that when you initialize the oauth method,
# you do not need to set
# The property variable, as it will be set automatically
# after initialization.
# But you can assign other string objects to it or make a call to it.

Parameters:: oauth (dict) – A dictionary containing the client and secret information and any other client information that can be represented within the data structure.
Returns:: None
Return type:: None

post(url, *args, payload=None, **kwargs)¶

A post request to HTTP request.

Parameters:

url (str) – A valid URL
args (Any) – Additional arguments if any
payload (dict | None) – A JSON data representation
kwargs – Additional keyword arguments to requests module

Returns:

An HTTP response

Return type:

Response

put(url, *args, payload=None, **kwargs)¶

A put request to HTTP request.

Parameters:

url (str) – A valid URL
args – Additional arguments if any
payload (dict | None) – A JSON data representation
kwargs – Additional keyword arguments to requests module

Returns:

An HTTP response

Return type:

Response

property save_oauth: str¶: Defines the OAuth data to save.

token_session(email=None, token=None, sess=None, _type='Bearer')¶

A session initializer to HTTP request.

Added in version 0.7.1.

_type - Datatype(string) - Allows a change of the Authorization type

Added in version 0.6.5.

sess - Datatype(string) - Allows the use of an Authorization header

Parameters:

email (str | None) – An email address or username
token (str | None) – An API token or user password
sess (str | None) – Triggers an Authorization bearer session
_type (str) – An acceptable Authorization type e.g. Bearer or JWT or …

Returns:

None

Return type:

None

field¶

Alias to the field class and it basically helps to update custom or system fields on Jira. You can access this class and make updates to Jira fields.

from jiraone import LOGIN, field, echo

# previous login statement
issue = "T6-75"
fields = "Multiple files" # a multi-select custom field
case_value = ["COM Row 1", "Thanos"]
for value in case_value:
    c = field.update_field_data(data=value, find_field=fields, key_or_id=issue, options="add", show=False)
    echo(c)

class jiraone.access.Field¶

Field class helps with Jira fields.

It helps with posting, putting and getting various fields or field type.

It comes with two attributes
- field_type
- field_search_key

static cascading(data=typing.Any)¶

Transform a string or a list into a cascading select type.

Parameters:: data (Any) – A string or list content
Returns:: A list object or none.
Return type:: Any

static data_load(data=typing.Any, s=None)¶

Process the received data into a dict.

Parameters:

s (Any | None) – Any object to change s to not None
data (Any) – any object

Returns:

A dictionary content

Return type:

Dict

static extract_issue_field_options(key_or_id=None, search=None, amend=None, data=typing.Any)¶

Get the option from an issue.

Use this method to extract and amend changes to system fields such as Components or fix versions, labels or custom fields such a multicheckboxes or multiselect.

Parameters:

key_or_id (str | int | None) – Issue key or id of an issue.
search (Dict | None) – Issue data of an issue or issue payload.
amend (str | None) – Available option “add” or “remove” condition to decide action for appending.
data (Any) – Our object data that will be processed.

Returns:

List or None

Return type:

Any

static get_field(find_field=None)¶

Search for system fields or custom fields.

Parameters:: find_field (str | None) – A field name to search.
Returns:: A dictionary if field is found else None
Return type:: Any

get_field_value(name, keys)¶

Return the value of a field on an issue.

Parameters:

name (str) – The name of a field.
keys (str | int) – The issue key or issue id of an issue.

Returns:

Any datatype is returned

Return type:

Any

static multi_field(data=typing.Any, s='value')¶

Transform any given string separated by comma into an acceptable multi value string.

Parameters:

data (Any) – any string object data.
s (str) –
is a placeholder to determine the object key.
- e.g. required payload [{“value”: “hello”}] -> for
  Multicheckboxes type of field.
- e.g. required payload [{“name”: “hello”}] -> for
  Components or Fix versions type of field.

Returns:

A list of data

Return type:

List

static search_field(find_field=None)¶

Search for custom fields.

Note

When using on Jira Server or DC, this method will return all fields.

Parameters:: find_field (str | None) – A field name to search.
Returns:: A dictionary if field is found else None
Return type:: Any

update_field_data(data=None, find_field=None, field_type='custom', key_or_id=None, show=True, **kwargs)¶

Field works for.

All field types mentioned on the Field class attributes.

Request PUT:

Parameters:

data (Any | None) – The data you’re trying to process, depending on what field it could be any object.
find_field (str | None) – Name of the custom field or system field to find in strings.
field_type (str) – Available options - system or custom.
key_or_id (str | int | None) – Issue key or id of an issue.
show (bool) – Allows you to print out a formatted field that was searched.
kwargs –
Perform other operations with keyword args
- options arg is a string and has two values
”add” or “remove”.
- query arg is a string, and it can have any value
that is stated on the endpoint.issue() method
e.g. query=”notifyUsers=false”

Returns:

Any

Return type:

Any

For¶

The For class shows an implementation of a for loop. It comes with a special method that helps with dictionary indexing.

class jiraone.access.For(data, limit=0)¶

A Class to show the implementation of a ‘for’ loop.

It calls the __iter__ magic method then the __next__ method and raises a StopIteration once it reaches the end of the loop. Datatype expected are list, dict, tuple, str, set or int.

Example 1:

from jiraone import For

data = {"work": "home", "house": 2}
result = For(data)
print(list(result))
# [{'work': 'home'}, {'house': 2}]

accessing dictionary index using private method __dictionary__

Example 2:

# previous expression
print(result.__dictionary__(1))
# {'house': 2}

The above shows how you can call an index of a dictionary object.

Example 3:

from jiraone import For

data = "Summary"
result = For(data)
print(list(result))
# ['S', 'u', 'm', 'm', 'a', 'r', 'y']

Basically you can get a list of any data structure used. For integers, it creates a range of those numbers

Parameters:

data (list | tuple | dict | set | str | int)
limit (int)

manage¶

The manage class is an alias to the usermanage-class class of the management module. It focuses primarily on user and organization management. The authentication is different as it uses a bearer token.

from jiraone import manage

token = "Edfj78jiXXX"
manage.add_token(token)

class jiraone.management.UserManagement¶

The UserManagement API is used to access organization profiles on Atlassian sites. The alias to this class is called manage

It comes with the below attributes and methods.

token = "YUISNxxx"
manage.api_token(token)
manage.LINK  # attribute
manage.AUTH  # attribute

add_token(token)¶

Adds a Bearer token to authenticate the API.

Parameters:: token (str) – An API key
Returns:: None
Return type:: None

api_token(account_id, method='GET', token_id=None)¶

Gets the API tokens owned by the specified user or Deletes a specified API token by ID.

Parameters:

account_id (str) – A user string value for Atlassian accounts
method (str) – A response method condition
token_id (str | None) – A user token id to be deleted.

Returns:

Any

Return type:

Any

property domain_id¶: Get property of organization domain id

property event_id¶: Get property of organization event id

static find_user(query, source=None)¶

Finds a specific user.

Parameters:

query (str) – A search term, could be an email, displayname or accountId if the source data is gotten from self.get_all_users and parameter detail=True
source (List | None) – A list of users

Returns:

A dict of the user data or a list of the data

Return type:

Dict | List

get_all_users(source, detail=False)¶

Store all user list from organization, so we can search them by email.

from jiraone import manage as org

token = "VGHxxxxx"
org.add_token(token)
get_users = org.get_organization(org.org_id, filter_by="users").json()
all_users = org.get_all_users(get_users)
# output is a deque list, which can be accessed like a regular list.
print(all_users)

Parameters:

source – A JSON response payload
detail (bool) – Bool defaults to False

Returns:

Deque List

Return type:

deque

get_organization(org_id=None, filter_by=None, domain_id=None, event_id=None, action=True, policy_id=None, **kwargs)¶

GET request for the organization API.

Returns a list of your organizations (based on your API key).

Returns information about a single organization by ID.

Returns a list of users in an organization.

Returns a list of domains in an organization one page at a time.

Returns information about a single verified domain by ID.

Returns information about a single event by ID.

Returns information about org policies.

Returns information about a single policy by ID.

Parameters:

org_id (str | None) – Retrieve the organization id from the API key
domain_id (str | None) – Retrieve domain details
filter_by (str | None) –
Use to determine the endpoint to return

Valid options
- users - return the users in an organization
- domains - list of domains in an organization
- events - list of events in an audit log
- policies - get the policy of the organization
event_id (str | None) – Use to determine the events in the audit log
action (bool | None) –

Additional positional argument for events.
True sets events-actions
- action - Sets the event actions, true to enable by
  default set to true. e.g. action=True
policy_id (str | None) – An id of the policy
kwargs (Any) –
Optional arguments

Valid options

Any response argument

e.g. json=payload
data=payload

Returns:

Any

Return type:

Any

get_user_permission(account_id, query=None)¶

Returns the set of permissions you have for managing the specified Atlassian account.

Parameters:

account_id (str) – A user string value for Atlassian accounts
query (list | None) –
A query parameter of Array<string>

Valid options

Valid values: profile, profile.write, profile.read, email.set, lifecycle.enablement, apiToken.read, apiToken.delete

Returns:

Any

Return type:

Any

manage_organization(org_id, method='POST', policy_id=None, resource_id=None, **kwargs)¶

Create, put and delete organization data. Create a policy for an org Send a post request by using method=”post” as keyword args. Update a policy for an org. Send a put request by using method=”put” as keyword args. You need to send a payload for the body using the example shown below

{
      "id": "<string>",
      "type": "policy",
       "attributes": {
        "type": "ip-allowlist",
         "name": "<string>",
          "status": "enabled",
          "rule": {},
           "resources": [
                           {
                         "id": "<string>",
                          "meta": {
                            "scheduledDate": "<string>",
                            "migrationStartDateTime": "<string>",
                              "migrationEndDataTime": "<string>",
                               "atlassianAccountId": "<string>"
                       },
                       "links": {
                        "ticket": "<string>"
                            }
                     }
          ]
        }
}

Delete a policy for an org.

Parameters:

org_id (str) – ID of the organization to create policy for
method (str) –
A response method to set

Valid options
- PUT - updates resource
- POST - creates resource
- DELETE - removes resources
policy_id (str | None) – ID of the policy
resource_id (str | None) – Resource ID
kwargs (Any) – Additional data to sent in request body

Returns:

Any

Return type:

Any

manage_profile(account_id, method='GET', **kwargs)¶

Returns information about a single Atlassian account by ID by using a “GET” request.

Request PATCH:

Updates fields in a user account.

Parameters:

account_id (str)
method (str)
kwargs (Any)

Return type:

Any

The profile.write privilege details which fields you can change.

Request PUT:

Sets the specified user’s email address.

Parameters:

account_id (str)
method (str)
kwargs (Any)

Return type:

Any

Before using this endpoint, you must verify the target domain

Parameters:

account_id (str) – A user string value for Atlassian accounts
method (str) –
A response method condition

Available options

request GET:

Get the return request

request PATCH:

Updates a given set of data

body parameter:

Any or all user object

this is value

Example:

e.g. {“name”: “Lila User”, “nickname”: “marshmallow”}

request PUT:

Change the email account of the user
kwargs (Any) –
- Contains other options passed to the requests.<patch>

Body parameter:

email - string

Example:

e.g. {“email”: “prince.nyeche@elfapp.website”}

Return type:

Any

# previous expression
# json=<variable_name>
payload = {"email": "prince.nyeche@elfapp.website"}
manage.manage_profile("account_id", "<method>", json=payload)

Returns:

Any

Parameters:

account_id (str)
method (str)
kwargs (Any)

Return type:

Any

manage_user(account_id, disable=True, **kwargs)¶

Disables the specified user account. The permission to make use of this resource is exposed by the lifecycle.enablement privilege.

OR

Enables the specified user account.

The permission to make use of this resource is exposed by the lifecycle.enablement privilege.

Parameters:

account_id (str) – A user string value for Atlassian accounts
disable (bool) – A bool option, if True this API url is set to disabled
kwargs –
Additional keyword argument to pass body data

Options available when disable is False

Return type:

Any

# previous expression

payload = {"message": "On 6-month suspension"}
manage.manage_user("account_id", json=payload)

Returns:

Any

Parameters:

account_id (str)
disable (bool)

Return type:

Any

property org_id¶: Get property of organization id

property org_ids¶: Get property of organization ids

property policy_id¶: Get property of organization policy id

PROJECT¶

This is an alias to the PROJECT class of the reporting module. It performs various project reporting task and data extraction.

from jiraone import LOGIN, PROJECT

# previous login statement
jql = "project = ABC ORDER BY Rank DESC"
PROJECT.change_log(jql)

class jiraone.reporting.Projects¶

Get report on a Project based on user or user’s attributes or groups.

static async_change_log(jql, *, folder='ChangeLog', file='change_log.csv', **kwargs)¶

Extract the issue history of an issue asynchronously.

Query the changelog endpoint if using cloud instance or straight away define access to it on server. Extract the histories and export it to a CSV file.

Parameters:

jql (str) – (required) A valid JQL query for projects or issues.
folder (str | None) – A name to a folder where the history file will be stored.
file (str | None) – A name to the exported file result.
kwargs (Any) –

The acceptable kwargs that can be passed to the
async_change_log method are given below. Like your change_log method, this allows some of the same arguments in the change_log method with some additional arguments that makes its iteration much faster than your regular change_log method.
- workers: Datatype(int) The number of thread processes to
  begin with.
- timeout: Datatype(float or int) - A number to denote the thread
  process timeout.
- field_name: Datatype(str) - Target a field name to render.
- flush: Datatype(int) - Delay the time, so any running thread
  can finish.

Returns:

None

Return type:

None

static byte_converter(val)¶

1 Byte = 8 Bits.

using megabyte MB, value is 1000^2

mebibyte MiB, value is 1024^2

total = val / MB

Parameters:: val – A value to supply
Returns:: strings
Return type:: str

static bytes_converter(val)¶

Returns unit in KB or MB.

1 Byte = 8 Bits.

using megabyte MB, value is 1000^2

mebibyte MiB, value is 1024^2

total = val / MB

Parameters:: val – An integer value
Returns:: string
Return type:: str

static change_log(folder='ChangeLog', file='change_log.csv', back_up=False, allow_cp=True, **kwargs)¶

Extract the issue history of an issue.

Query the changelog endpoint if using cloud instance or straight away define access to it on server. Extract the histories and export it to a CSV file.

Parameters:

folder (str) – A name of a folder datatype String
file (str) – A name of a file datatype String
back_up (bool) – A boolean to check whether a history file
allow_cp (bool)
kwargs (str | bool)

Return type:

None

is exist or not.

Parameters:

allow_cp (bool) – Allow or deny the ability to have a checkpoint.
kwargs (str | bool) –
The other kwargs that can be passed as below.
- jql: (required) A valid JQL query for projects or issues.
datatype -> string
- saved_file: The name of the file which saves the iteration.
datatype -> string
- show_output: Show a printable output on terminal.
datatype -> boolean
- field_name: Target a field name to render.
datatype -> string
folder (str)
file (str)
back_up (bool)

Returns:

None

Return type:

None

comment_on(key_or_id=None, comment_id=None, method='GET', **kwargs)¶

Comment on a ticket or write on a description field.

Request GET:

comments

Request POST:

comments by id

Request PUT:

update a comment

Request POST:

add a comment

Request DELETE:

delete a comment

Parameters:

key_or_id (str | None)
comment_id (int | None)
method (str)

Return type:

Any

Do the same thing you do via the UI.

Returns:

Any

Parameters:

key_or_id (str | None)
comment_id (int | None)
method (str)

Return type:

Any

static dashboards_shared_with(dashboard_folder='Dashboard', dashboard_file_name='dashboard_file.csv', **kwargs)¶

Retrieve the Dashboard Id/Name/owner and who it is shared with.

The only requirement is that the user querying this API should have access to all the Dashboard available else it will only return dashboard where the user’s view access is allowed.

Parameters:

dashboard_folder (str) – A folder
dashboard_file_name (str) – A file to store temp data
kwargs – Additional arguments

Returns:

None

Return type:

None

static date_converter(val)¶

split the datetime value and output a string.

Parameters:: val – A value to be supplied
Returns:: string
Return type:: str

static download_attachments(file_folder='Attachment', file_name='attachment_file.csv', download_path='Downloads', attach=8, skip_csv_header=True, overwrite=True, create_html_redirectors=False, **kwargs)¶

Go through the attachment list CSV file named file_name and located in the file_folder; for each row, download the attachment indicated to your local device.

Calling this method with default arguments assumes that you’ve previously called the def get_attachments_on_project() method with default arguments.

To avoid conflicts whenever attachments have the same filename (e.g. screenshot-1.png), each downloaded attachment will be placed in a separate directory which corresponds to the content ID that Jira gives the attachment.

Parameters:

download_path (str) – the directory where the downloaded attachments are to be stored
file_folder (str) – the directory where the attachment list CSV file can be found (Default corresponds to the output of def get_attachments_on_project() when called with default arguments)
file_name (str) – file name of the attachment list CSV file (Default corresponds to the output of def get_attachments_on_project() when called with default arguments)
attach (int) – index of the column that corresponds to ‘Attachment URL’ in the attachment list CSV file. (Default is 8, which corresponds to the output of def get_attachments_on_project())
skip_csv_header (bool) – when set to True, skips the first line of the attachment list CSV file; i.e. assumes that the first line represents a header row. (Default is True, which corresponds to the output of def get_attachments_on_project())
overwrite (bool) – when True, any attachments will be overwritten. When False, downloading of the attachment will be skipped. Setting this to False can significantly speed up incremental backups by only downloading attachments that have not yet been downloaded.
create_html_redirectors (bool) – is used when you want to use the downloaded attachments as part of a website to mirror and serve the attachments separately from the Jira website. When set to True, an index.html will be created for each attachment so that the original Jira Attachment URL, e.g. https://yourorganization.atlassian.net/rest/api/3/attachment/content/112736 , can be more easily rewritten to something like https://yourmirrorsite.com/jiraone/MYPROJ/attachment/content/112736 . The index.html will take care of the HTTP redirect that will point to the attachment with the original filename.
kwargs –
Additional keyword argument

Acceptable options
- file: index of the column ‘Name of file’ in the attachment list CSV file.
  (Default is 6, which corresponds to the output of def get_attachments_on_project())

Returns:

None

Return type:

None

static export_issues(*, folder='EXPORT', jql=None, page=None, **kwargs)¶

Exports all Jira issue either in CSV or JSON format based on JQL search. If the number of issues returned is greater than 1K issues, all the issues are finally combined into a single file as output.

Parameters:

folder (str | None) – The name of a folder, where files will be stored.
jql (str | None) – A valid JQL (required) if merge_files args is not provided
page (tuple | None) – An iterative counter for page index denoting the pagination for JQL search
kwargs (Any) –
Additional arguments that can be supplied.

Available options
- temp_file: Datatype (str) A temporary file name
when combining the exported file.
- final_file: Datatype (str) Name of the final
combined CSV or JSON file name.You do not need to add the extension as this is added automatically based on the extension argument.
- target: Datatype (str or dict) Ability to change or get
certain values from another instance. If and only if it is the same user who exist on both. As the same authentication needs to be used to extract or create the data else use a dict to construct a login acceptable form that can be used as authentication. This needs to be set for the fields argument to work properly.

When used as a string, just supply the instance base URL as string only.

Example:
```
# previous expression
base = "https://yourinstance.atlassian.net"
```
Example of dict construct which can be stored as a .json file.

Example:
```
{
 "user": "prince@example.com",
 "password": "secretpassword",
 "url": "https://server.example.com"
}
```
- fields: Datatype (list) Ability to alter the row value
of a field. Useful when you want to change the value used for imports into Jira. Such as sprint name to id or username to accountId (Server or DC to cloud migration). This argument requires the target argument to be set first before it can become useful.
- encoding: Datatype (str) Ability to alter the encoding
of the exported data to file_writer function.
- errors: Datatype (str) Ability to alter the error type used
in encoding argument if the encoded character fails to decode.
- extension: Datatype (str) Ability to export the issues in
either CSV or JSON format. e.g. options are “csv” or “json”

Example:
```
# previous statements
PROJECT.export_issues(jql=jql, extension="csv")
```
- field_type: Datatype (str) Ability to define if all fields
or default fields are exported. e.g. options are “all” or “current”. The default is set to “all” for every field.If you want to export only default fields, set it to “current”. This will export the default field your current users has defined on the UI.

Example:
```
# previous statements
my_current_field = "current"
PROJECT.export_issues(jql=jql, field_type=my_current_field)
```
- exclude_fields: Datatype (list) Ability to exclude certain
fields from the exported file. This field must be an exact string of the custom field name. This argument cannot be used when include_fields args is not empty

Example:
```
# previous statements
fields = ["Labels", "Comment", "SupportTeam"]
PROJECT.export_issues(jql=jql, exclude_fields=fields)
```
- include_fields: Datatype (list) Ability to include certain
fields from the exported file. This field must be an exact string of the custom field name. This argument cannot be used when exclude_fields is not empty.

Example:
```
# previous statements
fields = ["Summary", "Comment", "SupportTeam"]
PROJECT.export_issues(jql=jql, include_fields=fields)
```
- workers: Datatype (int) Ability to use process workers for
faster iterations. This helps during http request to endpoints. By default, 4 threads are put into motion

Example:
```
# previous statement
workers = 20
PROJECT.export_issues(jql=jql, extension="json",
workers=workers)
```
- is_sd_internal: Datatype (bool) Ability to add additional
properties to a JSON comment export for JSM projects. This argument expects that a comment field column must include an addition string attribute as “true” or “false” specifically tailored for JSM projects.

Example:
```
# Given the below is a CSV row of a comment field
"25/Apr/22 11:15 AM;
557058:f58131cb-b67d-43c7-b30d-6b58d40bd077;
Hello this work;true"
```
The last value there “true” will determine the visibility of
a comment on a JSM project import.
- merge_files: Datatype (list) Ability to combine various CSV
files not necessarily Jira related into a single CSV file. You can supply the filename in a list e.g.

Example:
```
# previous statements
my_files = ["file1.csv", "file2.csv", file3.csv"]
PROJECT.export_issues(merge_files=my_files)
```
When merge_files argument is used, it overrides other arguments such as jql, page, encoding and errors. Please ensure that these files are in the same directory as

indicated by the folder argument
- csv_to_json: Datatype (str) Ability to provide a CSV Jira
export to be converted to JSON format. This argument expects the name of the CSV file name. It expects a “Project key” column to be included in the CSV file.
- timeout: Datatype (float or int) Ability to increase the
timeout period required for the workers argument. If you do increase the workers argument, you have to set a plausible timeout that allows all thread to join and finish executing to prevent errors e.g. KeyError
- json_properties: Datatype (list) Ability to add additional
properties to the JSON export option such as users or links objects. Examples of valid properties: users, links and history

Example:
```
# previous statements
props = ["users", "links"]
jql = "project in (ABC, IT)"
PROJECT.export_issues(jql=jql, extension="json",
json_properties=props)
```
- check_auth: Datatype (bool) Ability to turn off or on the
authentication check that the export function uses. Only useful when merge_files argument is used alone.

Example:
```
# previous statements
my_files = ["file1.csv", "file2.csv", "file3.csv"]
PROJECT.export_issues(merge_files=my_files,
     check_auth=False)
```
- date_format: Datatype (str) Ability to use certain date
pattern to parse datetime Jira fields. Useful for datetime custom field

Example:
```
# previous statements
date_pattern = "%d/%m/%Y %I:%M %p"
# The above would translate into dd/MM/YYYY 09:14 AM
jql = "project in (ABC, IT)"
PROJECT.export_issues(jql=jql, extension="json",
date_format=date_pattern)
```
- json_custom_type: Datatype (list) Ability to exclude
certain customType from the JSON export. The name has to be an exact string or unique starting string of the custom type. By default, this argument omits two custom type of which one of such custom type is given in the below example

Example:
```
# previous statements
_type = ["com.atlassian.plugins.atlassian-connect-plugin"]
# The above is referring to the custom field type
jql = "project in (ABC, IT)"
PROJECT.export_issues(jql=jql, extension="json",
json_custom_type=_type)
```
- is_cache: Datatype (bool) Ability to save frequently used
http call if the same request is done within a given amount of time for faster iterations.
- use_cache: Datatype (bool) Ability to use cached http call
object at will. This allows the use of previously saved objects. If none exist, a new http call is made and the data is saved as an JSON object used as cache.
- is_cache_filename: Datatype (str) Ability to name the file
used to store the cached data.
- expires: Datatype (int) Ability to add an expiry timeframe
to the is_cache argument expressed in days, which allows caching to be recalled or valid over a period of time in days.

Example:
```
# previous statements
expiry_time = 30 # number of days
jql = "project in (ABC, IT)"
PROJECT.export_issues(jql=jql, extension="json",
expires=expiry_time, is_cache=True)
```
- allow_media: Datatype (bool) Ability to add a user
credential to each attachment uri of the “Attachment” column of a CSV export. This helps to easily append credentials to all rows of the CSV export with your current credentials.
- sub_tasks: Datatype (list) Ability to identify all the
sub-tasks issues present in a JSON export. Useful when you want to provide issue links between a parent and child issues
- project_type - Datatype(dict) Ability to provide a project
template for JSON creation based on the project type

Example:
```
# previous expression
template = {
"software":
"com.pyxis.greenhopper.jira:gh-simplified-scrum-classic"}
PROJECT.export_issues(jql=jql, extension="json",
project_type=template)
```
- workflows - Datatype(dict) Ability to provide a map of
project key to workflow scheme name that exist on your destination instance.

Example:
```
# previous expression
# Where ITSEC is the project key
workflow = {"ITSEC":"Software Simplified Workflow Scheme"}
PROJECT.export_issues(jql=jql, extension="json",
workflows=workflow)
```
- flush - Datatype ( float or int) Ability to set a delay
period required for running threads to shut down. Required for history extraction.
- delimit - Datatype(str) Ability to change the CSV file
separator. The default is a comma.

Example:
```
# previous import
PROJECT.export_issues(jql=jql, extension="csv",
delimit=";")
```
- show_export_link - Datatype(bool) Ability to print out
the export file link after it completes. Defaults to True

Return type:

None

Changed in version 0.7.4.

encoding: Helps determine how encoding are handled.

errors: Helps determine decoding errors are handled.

Changed in version 0.7.6.

extension: Determines the file export format in CSV or JSON format.

field_type: Specifies if export should contain all fields or default fields.

exclude_fields: Exclude certain fields from the exported data in CSV.

workers: Indicates how many threads to use at a go when making http request.

is_sd_internal: Adds additional properties to a comment field in JSON format. This argument expects that a comment field must include an addition string attribute as “true” or “false” specifically tailored for JSM projects.

merge_files: Merge series of CSV files into one which are located in the same director fed as a list of file names.

csv_to_json: When supplied a dir path to Jira CSV file, auto converts to Jira JSON form.

timeout: Used in conjunction with the workers argument for threads wait time.

json_properties: Used in JSON export to include other attributes to the exported file.

check_auth: Used as a flag to turn on or off Jira auth validation error.

include_fields: Used to include only certain Jira fields in a CSV export.

date_format: Used to parse datetime custom fields.

json_custom_type: Used to exclude certain custom field type from being added to the export list in JSON format.

is_cache: Used to cache dict or list result objects that have used some http request in the past for faster lookup.

use_cache: Allow the use of cached objects such as custom fields and users objects.

is_cache_filename: The name of the file used to store cached data. It should be in a .json format.

expires: Used in conjunction to is_cache argument to allow the caching to be valid over a given period of time.

allow_media: Allows auth to be added to each media file in a CSV export.

sub_tasks: Used to identify sub-task names in JSON export.

project_type: Project template types.

workflows: Project workflow scheme names.

flush: Delay timing when threads are still running for history extraction.

Changed in version 0.7.9.

delimit: Allows the ability to change the CSV file separator

show_export_link: Allows the ability to print out the exported file link

Returns:

None

Raises:

IndexError, AttributeError, KeyError, TypeError, ValueError, JiraOneErrors

Parameters:

folder (str | None)
jql (str | None)
page (tuple | None)
kwargs (Any)

Return type:

None

static get_all_roles_for_projects(roles_folder='Roles', roles_file_name='roles_file.csv', user_extraction='role_users.csv', **kwargs)¶

Get the roles available in a project and which user is assigned to which role within the project.

Parameters:

roles_folder (str) – A folder
roles_file_name (str) – A file to store temp data
user_extraction (str) – Data extraction file holder
kwargs – Addition argument

Returns:

None

Return type:

None

get_attachments_on_projects(attachment_folder='Attachment', attachment_file_name='attachment_file.csv', mode='w', **kwargs)¶

Fetch the list of all the attachments of a Project or Projects and write it out to an attachment list CSV file named attachment_file_name located in attachment_folder.

Also, get the size of the attachment for each Issue, sum up the size of all attachments, and output the total for all Projects as the last row of the output attachment list CSV file.

JQL is used to search for the attachments.

Parameters:

attachment_folder (str) – Target directory where the attachment list CSV file will be written.
attachment_file_name (str) – Filename of the attachment list CSV to be written.
mode (str) – Write mode for attachment list CSV to be written. By default it is ‘w’, which means that any existing file will be overwritten. For example, set to ‘a’ if you want to append to instead of truncating any existing file.
kwargs – Additional arguments to specify.

Return type:

None

static get_total_comments_on_issues(folder='Comment', file_name='comment_file.csv', **kwargs)¶

Return a report with the number of comments sent to or by a reporter (if any).

This api will return comment count, the total comment sent by a reporter per issue and collectively sum up a total. It also shows how many comments other users sent on the issue.

Parameters:

folder (str) – The name of a folder
file_name (str) – The name of a file
kwargs – additional argument to supply

Returns:

None

Return type:

None

static grade_and_sort(attach_list, read_file)¶

Arranges and sorts the data.

Parameters:

attach_list – A list of data
read_file – A data set

Returns:

A union of float and integers

Return type:

float | int

static issue_count(jql)¶

Returns the total count of issues within a JQL search phrase.

Parameters:: jql – A valid JQL query (required)
Return type:: dict

Returns:: a dictionary, containing issue count & max_page
Parameters:: jql (str)
Return type:: dict

static move_attachments_across_instances(attach_folder='Attachment', attach_file='attachment_file.csv', key=3, attach=8, **kwargs)¶

Ability to post an attachment into another Instance.

given the data is extracted from a csv file which contains the below information

Issue key

file name

attachment url

we assume you’re getting this from def get_attachments_on_project()

Parameters:

attach_folder (str) – a folder or directory path
attach_file (str) – a file to a file name
key (int) – a row index of the column
attach (int) – a row index of the column
kwargs –
Additional arguments
Acceptable options
- file: Specify the index of the columns. Integer
  datatype expected.
- last_cell: Determines if the last cell
  should be counted. Bool datatype expected.
For example:
```
 e.g.
* key=3,

* attach=6,

* file=8
```

Return type:

None

the above example corresponds with the index if using the def get_attachments_on_project() otherwise, specify your value in each keyword args when calling the method.

return:

None

static projects_accessible_by_users(*args, project_folder='Project', project_file_name='project_file.csv', user_extraction_file='project_extract.csv', **kwargs)¶

Send an argument as String equal to a value, example: status=live.

Multiple arguments separate by comma as the first argument in the function, all other arguments should be keyword args that follows. This API helps to generate full user accessibility to Projects on Jira. It checks the users access and commits the finding to a report file.

You can tweak the permission argument with the options mention here

for endpoint /rest/api/3/user/permission/search

Parameters:

args (str) – A set of parameter arguments to supply
project_folder (str) – A folder
project_file_name (str) – A file to hold temp data
user_extraction_file (str) – A file to hold user temp data
kwargs –
Additional arguments

Acceptable options
- permission: A permission of Jira to check

Return type:

None

Returns:

None

Parameters:

args (str)
project_folder (str)
project_file_name (str)
user_extraction_file (str)

Return type:

None

static view_issues(*, project_key_or_id=None, key_or_id=None)¶

View all issues and its properties

Parameters:

project_key_or_id (str | int | None)
key_or_id (str | int | None)

Return type:

None

USER¶

This is an alias to the USER class of the reporting module. It contains methods that are used to easily get user details.

from jiraone import LOGIN, USER

# previous login statement
USER.get_all_users(file="user.csv", folder="USERS")

class jiraone.reporting.Users¶

This class helps to Generate the No of Users on Jira Cloud

You can customize it to determine which user you’re looking for.

It’s method such as get_all_users displays active or inactive users,
so you’ll be getting all users

get_all_users(pull='both', user_type='atlassian', file=None, folder=typing.Any, **kwargs)¶

Generates a list of users.

param pull:

(options) for the argument

both: pulls out inactive and active users

active: pulls out only active users

inactive: pulls out inactive users

Parameters:

user_type (str) –
(options) for the argument
- atlassian: a normal Jira Cloud user
- customer: this will be your JSM customers
- app: this will be the bot users for any Cloud App
- unknown: As the name suggest unknown user type
file (str | None) – String of the filename
folder (str) – String of the folder name
kwargs –
Additional keyword argument for the method.

return:

Any
pull (str)

Return type:

None

get_all_users_group(group_folder='Groups', group_file_name='group_file.csv', user_extraction_file='group_extraction.csv', **kwargs)¶

Get all users and the groups associated to them on the Instance. :return: None

Parameters:

group_folder (str)
group_file_name (str)
user_extraction_file (str)

Return type:

None

mention_user(name)¶

Return a format that you can use to mention users on cloud. :param name: The name of a user.

Returns:: List[str]
Return type:: List[str]

report(category=typing.Any, filename='users_report.csv', **kwargs)¶

Creates a user report file in CSV format. :return: None

Parameters:

category (str)
filename (str)

Return type:

None

search_user(find_user=None, folder='Users', **kwargs)¶

Get a list of all cloud users and search for them by using the displayName.

Parameters:

find_user (str | list | None) – A list of user’s displayName or a string of the displayName
folder (str) – A name to the folder
kwargs –
Additional arguments

options
- skip (bool) - allows you to skip the header
of file_reader
- delimiter (str) - allows a delimiter to the
file_reader function
- pull (str) - determines which user is available
e.g. “active”, “inactive”
- user_type (str) - searches for user type
e.g “atlassian”, “customer”
- file (str) - Name of the file

Return type:

list | int

user_activity(status=typing.Any, account_type=typing.Any, results=typing.Any)¶

Determines users activity.

Returns:

None

Parameters:

status (str)
account_type (str)
results (List)

Return type:

None

Module¶

The module module contains functions that are specific towards a certain task. Each function is designed to be as straightforward as possible, so you can easily make calls to Jira’s endpoint and get the required data.

from jiraone import LOGIN, USER, echo, field
from jiraone.module import field_update
import json

# a configuration file which is a dict containing keys user, password and url
config = json.load(open('config.json'))
LOGIN(**config)

key = 'ITSM-4'
name = 'Last Update User'  # A single user picker field

if __name__ == "__main__":
    change = USER.search_user('Prince Nyeche')[0].get('accountId')
    make = field_update(field, key, name, data=change)
    echo(make)

# output
# <Response [204]>

jiraone.module.field_update()¶

jiraone.module.time_in_status(var, key_or_id, reader=None, report_file='time_status.csv', report_folder='TimeStatus', output_format=None, status=None, **kwargs)¶

Return a difference in time between two status or multiple statuses. across different sets of issues. Display the output or send the output into a file either in CSV or JSON.

Parameters:

var (Any) – Alias to the PROJECT which can invoke the change_log() method
key_or_id (str | int | List[str | int] | dict) –

An issue key or id or keys put in a list to
derive multiples values

or use a jql format in dictionary
reader (Callable | None) – file_reader function needs to be passed here
report_file (str | None) – A string of the name of the file
report_folder (str | None) – A folder where data resides
output_format (str | None) – An output format either in CSV or JSON. e.g. csv or json (case-insensitive)
status (str | None) – A status name to check or output.
kwargs (Any) –
Additional keyword arguments to use

Available options
- login - Required keyword argument to authenticate request
- pprint -Bool or Str, Optional - formats the datetime output into a nice pretty format. if true, false returns a readable less pretty format. Defaults to string “timestamp” which renders it with a datetime format.
- is_printable - Bool, prints output to terminal if true

# previous expression
# To print out the function, you can either use ``echo``
# function or ``print`` built-in
status = time_in_status(
PROJECT, key, file_reader, login=LOGIN, pprint=True, output_format="json",
                      is_printable=True)
echo(status)

Returns:

A Printable representation of the data or output files.

Parameters:

var (Any)
key_or_id (str | int | List[str | int] | dict)
reader (Callable | None)
report_file (str | None)
report_folder (str | None)
output_format (str | None)
status (str | None)
kwargs (Any)

jiraone.module.bulk_change_email(data, token)¶

Bulk change managed user’s email address if they do not exist.

Parameters:

data (str) – A string of the file name
token (str) – A string of the API token to authenticate the request

Return type:

None

Additionally, the output of failed attempts is written back to your data file.

Returns:

None

Parameters:

data (str)
token (str)

Return type:

None

jiraone.module.bulk_change_swap_email(data, token, **kwargs)¶

The function helps to swap an email address to another.

If the target email exist as an Atlassian account email, this will help to swap that email address to the desired target email.

Parameters:

data (str) – A string of the file name
token (str) – An API token to authenticate the API.
kwargs (Any) –
Additional keyword argument to pass

Valid values
- dummy - A dummy email address to choose if not a
default is formed from your email address
- users - The name of a file to check the users and
their account_id only needed if you want to search a predefined set of users.

Returns:

None

Return type:

None

Utils¶

class jiraone.utils.DotNotation(*args, **kwargs)¶

This DotNotation class provides the ability to use a dot notation on any dict object. Making it easier when working with dictionary objects. Examples below

from jiraone.utils import DotNotation

# for dict operation
my_dict = {"name": "John", "unit": 7}
notation =  DotNotation(my_dict)
print(notation.name)
# result
# >>> John

# for list[dict] operations
my_dict = [{"name": "John", "unit": 7}, {"name": "Jane", "unit" 8}]
notation =  DotNotation(value=my_dict)
print(notation.value[0].name)
# result - access the list using index
# >>> John

Note

When loading a list of dictionaries, please refer to the second example as shown on the above code. The dictionary needs to be assigned to a key (any naming convention will do) to get the value. Failure will result in an error.

class jiraone.utils.DateFormat¶: A representation of Python’s string directive for datetime formats

The DateFormat class provides the ability to construct datetime string directive which is used in Python’s datetime class.

from jiraone.utils import DateFormat

my_date = DateFormat.dd_MM_YYYY_hh_MM_AM_PM

jiraone.utils.process_executor(func, *, data=None, workers=4, timeout=2.5, **kwargs)¶

A process executor function. This function allows you to run asynchronous request on certain functions of jiraone, thus making multiple request at the same time.

Parameters:

func (Callable) – A function to act upon
data (Iterable | None) – A data that the function processes (an argument)
workers (int) – Number of threads to use and wait until terminates
timeout (float | int) – Specifies a timeout if threads are still running
kwargs – Additional arguments supplied to Thread class or the keyword arguments from the function

Returns:

None

Return type:

None

The process_executor helps to generate multiple threads used to make HTTP requests. To properly use this function, you should pass a function which has an argument in a for loop to begin the iteration. You can increase the number of threads to start with by increasing the workers argument

from jiraone.utils import process_executor

# a function called extract_issues(data)
# list_items a list of data
for items in list_items
    process_executor(extract_issues, data=items)

jiraone.utils.validate_on_error(name_field=None, data_type=None, err_message=None)¶

Validate an argument and prepares an error response

Example 1:

# import statements
name: str = "Mr. John"
validate_on_error(
       name,
       (str, "name", "a string"),
       "the name of a user in strings"
   )

The second example below shows how you can use multiple data type instance to check for the field_name.

Example 2:

# import statements
salary: Union[float, int] = 1230.45
validate_on_error(
       salary,
       ((float, int), "salary", "a number"),
       "a number to indicate the salary of a user"
   )

Parameters:

name_field (Any | None) – An argument field name
data_type (tuple | None) – The data type of the argument, it expects a datatype object, the name of the argument and a message which explains the expected object of the argument
err_message (str | None) – Expected error message

Returns:

None

Raise:

JiraOneErrors

Return type:

None

jiraone.utils.validate_argument_name(name_field, valid_args=None)¶

Validates the key word argument name and type of the argument

Parameters:

name_field (str) – The key word argument name
valid_args (dict | list | None) – The values of arguments expected

Returns:

None

Raise:

JiraOneErrors

jiraone

Navigation

Related Topics

API Documentation¶

endpoint¶

field¶

For¶

manage¶

PROJECT¶

USER¶

Module¶

Utils¶