dapritchard/jiraworklog

Command-line application to synchronize local worklog records with a Jira server

jiraworklog

jiraworklog is a command line application that synchronizes worklog entries between your local machine and a Jira server. The main functionality that it provides is:

• Reading your worklogs on your local machine from either a delimiter-separated values format such as CSV or an Excel format.
• Tracking any additions, modifications, or deletions of worklogs on your local machine and uploading the appropriate changes to your worklogs on the Jira server.

Once you have a configuration file set up then uploading worklogs to the Jira server is as simple as providing the worklogs to the jiraworklog application through standard input or via the --file argument.

> cat worklogs.csv
description,start,end,tags
Data pipeline,2021-01-12 10:00,2021-01-12 10:30,P9992-3
Write specifications,2021-01-12 13:15,2021-01-12 14:15,P9992-3

> jiraworklog --file worklogs.csv

Auto-confirm. The following changes will be made.

-- Add to remote worklogs ----------------------------------
Tuesday January 12, 2021
    P9992-3    10:00-10:30    (0:30)    Data pipeline
    P9992-3    13:15-14:15    (1:00)    Write specifications

Installation

jiraworklog is a Python application distributed through PyPI. If you have Python 3.9 or greater available on your machine then you can install it with a command like the following.

python -m pip install jiraworklog --user

Basic usage

Overview

jiraworklog requires a configuration file to be set up providing information about how to parse local worklog entries and Jira server authentication, among other things. Once the configuration file has been set up, provide your worklogs to the jiraworklog application either through standard input or via the --file argument. The application determines whether there have been any additions, modifications, or deletions of worklogs on your local machine and uploads the appropriate changes to your worklogs on the Jira server. When all of the worklogs that appear in the Jira server have been uploaded via jiraworklog, this amounts to synchronizing the worklogs from your local worklogs with the Jira server.

The other ways that worklogs can appear on the Jira server are through the Jira web application or web API. When worklogs are placed on the Jira server that jiraworklog isn't aware of, it effectively ignores those worklogs with the one exception that if an identical worklog is added to the local worklogs then it is considered to correspond to the appropriate remote worklog. This policy prevents jiraworklog from uploading the worklog a second time and also links the local and remote worklogs so that a future change in the local worklog results in a corresponding change to the remote worklog.

Viewing the available command-line options

Use the --help option to view the available command-line options.

jiraworklog --help

Reading in worklogs

If the local worklogs are stored in a file worklogs.csv then you can use a command like the following to upload your worklogs to the Jira server.

jiraworklog --file worklogs.csv

Similarly you can pass the local worklogs in via standard input.

cat worklogs.csv | jiraworklog

If you have an Excel file then you can also read it in using the --file option. Reading Excel files from standard input is currently not supported.

jiraworklog --file worklogs.xlsx

Jira authentication

Jira supports two forms of authentication for its API: basic authentication and OAuth. Currently only basic authentication is supported by jiraworklog.

Authentication to Jira via basic authentication requires the use of an API token. You can create a token if you do not have one by following the instructions found in the Manage API tokens for your Atlassian account page in the Atlassian Support website.

Configuration file setup

jiraworklog requires a configuration file to be set up providing information about how to parse local worklog entries and Jira server authentication, among other things. The configuration file setup is the most complicated part of getting jiraworklog up and running, but once it is set up you will usually not need to touch it except to specify new Jira issues.

You can see the full configuration file specification in Configuration file format. But usually the easiest way to create a new configuration file is by using the --init command-line option as shown in the following example. This will run an interactive script that prompts you for the necessary information and then constructs a configuration file for you using that information.

jiraworklog --init

Configuration file location

By default the jiraworklog application looks for the configuration file at ~/.jwconfig.yaml. If you store your configuration file at that location then you need only provide your worklogs when you invoke the jiraworklog application.

# Assumes that your configuration file is located at ~/.jwconfig.yaml
jiraworklog --file worklogs.csv

If your configuration file is not located in the default location then you can specify it by using the --config-path command-line option.

# Use the --config-path option if your configuration file is located in a
# non-default location (in this example at path/to/jwconfig.yaml)
jiraworklog --config-path path/to/jwconfig.yaml --file worklogs.csv

Configuration file format

The jiraworklog configuration file is expected to follow a YAML format.

An example of a valid configuration file is shown below. We'll break down the various elements in the following sections.

jwconfig_version: 0.1.0

basic_auth:
  server:    "https://runway.atlassian.net"
  user:      "[email protected]"
  api_token: "J6ab6YMa1HVWADNOmO6TC623"

issues_map:
  local-p1-1: "P01"
  local-p1-2: "P01"
  local-p2:   "P02"

# If you are using an Excel file then this field gets replaced by a
# `parse_excel` section (see below)
parse_delimited:
  col_labels:
    description: "task"
    start:       "start"
    end:         "end"
    tags:        "tags"
  col_formats:
    start:      "%Y-%m-%d %H:%M"
    end:        "%Y-%m-%d %H:%M"
    timezone:   "US/Eastern"
    delimiter2: ":"

Example parse_excel section.

# If you are using an Excel file then use a `parse_excel` section like
# the following in place of the `parse_delimited` section
parse_excel:
  col_labels:
    description: "task"
    start:       "start"
    end:         "end"
    duration:    null
    tags:        "tags"
  col_formats:
    timezone:   "US/Eastern"
    delimiter2: ":"

Configuration file version specification

The configuration file version specification is used so that the jiraworklog application knows how to read a given configuration file. An example version specification key value pair is shown below.

jwconfig_version: 0.1.0

jwconfig_version is a string providing the jiraworklog version for which the configuration file was written.

Configuration file authentication specification

Currently the only form of authentication supported by jiraworklog is basic authentication using an API token. An example basic authentication mapping is shown below. See the Jira authentication section for details on how to create an API token.

basic_auth:
  server:    "https://runway.atlassian.net"
  user:      "[email protected]"
  api_token: "J6ab6YMa1HVWADNOmO6TC623"

There are three possible keys within the basic_auth mapping. If you do not wish to store one or more of these values in the configuration file then you can instead provide a given value by using the corresponding environmental variable as described below.

• server: a string providing the server URL. If this value is omitted or null then jiraworklog reads in the information from the JW_SERVER environmental variable.
• user: a string providing the user ID, which is usually an email address. If this value is omitted or null then jiraworklog reads in the information from the JW_USER environmental variable.
• api_token: a string providing a user's API token. If this value is omitted or null then jiraworklog reads in the information from the JW_API_TOKEN environmental variable.

Configuration file issues mapping

The issues mapping section of the configuration file specifies a mapping of your local worklog tags to the names of the corresponding Jira issues. The names of the local tags and their corresponding Jira issue keys might be the same, but they need not be. You are also allowed to have multiple local tags map to the same Jira issue (thus your worklogs can be finer-grained than the Jira issues).

In the following example there are 3 mappings from local tags to Jira issues. The first entry maps worklogs tagged with local-p1-1to the Jira issue with key P01, while the second entry maps worklogs tagged with local-p1-2 to the same Jira issue with key P01. The last entry maps entries tagged with local-p2to the Jira issue with key P02.

issues_map:
  local-p1-1: "P01"
  local-p1-2: "P01"
  local-p2:   "P02"

There are 0 or more key/value pairs in the issues_map mapping (although note that there's nothing for jiraworklog to do when there are 0 entries). Each value must be a string corresponding to a Jira issue key, and multiple entries are allowed to correspond to the same Jira issue.

Configuration file worklog parsing

The worklog parsing section of the configuration file provides the information for jiraworklog to know how to read in the local worklogs. Currently jiraworklog supports either delimiter-separated values formats such as CSV or an Excel format.

In the event that your worklogs are represented using a delimiter-separated values format such as CSV then you will need to provide a parse_delimited section in the configuration file as described in the Delimiter-separated values worklog parsing section.

In the event that your worklogs are represented using an Excel format then you will need to provide a parse_excel section in the configuration file as described in the Excel worklog parsing section.

Delimiter-separated values worklog parsing

If your local worklogs are provided using a delimiter-separated values format such as CSV then you will need to provide a parse_delimited section in the configuration file in order to specify how the data is parsed by jiraworklog. An example parse_delimited section is shown below.

parse_delimited:
  col_labels:
    description: "task"
    start:       "start"
    end:         "end"
    duration:    null
    tags:        "tags"
  col_formats:
    start:      "%Y-%m-%d %H:%M"
    end:        "%Y-%m-%d %H:%M"
    timezone:   "US/Eastern"
    delimiter2: ":"
  dialect: {}

The parse_delimited mapping has two required entries, col_labels and col_formats, while an optional third entry dialect is allowed to be omitted or null (or to be an empty mapping for that matter, as shown in the preceding example).

• col_labels: a mapping of entries specifying the meaning of the relevant columns in the source data. For example, if you had a column in your data named Start Time corresponding to the worlog entry start datetimes, then you would provide an entry start: "Start Time" in the mapping.

  Only 2 out of 3 of the columns corresponding to the worklogs start, end, and durations are required, although all three can be provided.

  • description: a string specifying the name of the column providing the description of the worklog.
  • start: a string specifying the name of the column providing the start datetime of the worklogs (this can be omitted or null).
  • end: a string specifying the name of the column providing the end datetime of the worklogs (this can be omitted or null).
  • duration: a string specifying the name of the column providing the duration of the worklogs (this can be omitted or null). The duration can be provided in a form like "2h 30m", which would correspond to a duration of 2 hours and 30 minutes (i.e. 150 minutes). The valid units of time are w for weeks, d for days, h for hours, m for minutes, and s for seconds. Not every unit of time need be included in a given worklog duration entry.
  • tags: a string specifying the name of the column providing the tags for the worklogs. Tags are the mechanism that are used to identify which Jira issue, if any, that a given worklog corresponds to. A worklog is allowed to have multiple tags, although only one tag can correspond to a Jira issue. If there are multiple tags then they are specified using a string that is separated by the delimiter2 character. For example, if delimiter2 is specified as ":" and a given tags entry is data processing:P9992-3 then the tags would be data processing and P9992-3.

• col_formats: a mapping of entries providing various column parsing information.

  The start and end columns specify the formats in which the datetimes are provided. As an example, consider the datetime format 2021-01-29 15:45 representing the datetime of January 29th, 2021 at 15 hours and 45 minutes after midnight. The formatting string for this datetime format would be %Y-%m-%d %H:%M. The datetime entries are parsed by the Python function strptime which has formatting rules as described in the strftime() and strptime() Format Codes section of the datetime Python documentation.

  • start: a string specifying the worklogs start datetime format. This should be omitted or null if there is no start datetime column.

  • end: a string specifying the worklogs end datetime format. This should be omitted or null if there is no end datetime column.

  • timezone If your timezone information is already included within your worklog start and end datetime strings then this should be omitted or null. Otherwise, it is a string specifying your timezone.

    The list of allowed timezone strings can be found by running either python -c 'import pytz, prettyprinter; prettyprinter.pprint(pytz.common_timezones)' to see the most common timezones or python -c 'import pytz, prettyprinter; prettyprinter.pprint(pytz.common_timezones)' to see all available timezones.

  • delimiter2 a single-character string specifying the character upon which to split the tags (this can be omitted or null). If delimiter2 is omitted or null then no tag splitting is performed.

• dialect: a mapping specifying the parsing of the delimiter-separated values data (this can be omitted or null).

  jiraworklog uses Python's csv library, and the parsing options exposed to the user are exactly those provided by the library and which are described in the Dialects and Formatting Parameters section of the Python csv documentation. Any option can be omitted or null, in which case the default value defined by the csv library is used. Note that Dialect.strict is always set to True by jiraworklog.

  By default the csv library parses CSV files (i.e. Dialect.delimiter is specified as ',').

  The main complication when constructing delimiter-separated values data is what to do when the delimiter appears as part of one of the entries. One approach is to escape the delimiter using a predetermined escape character such as \. When the escape character itself appears in the data it is itself escaped so that \\ is interpreted as a literal \. Another approach is to quote an entire entry using a predetermined quoting character such as " so that for a CSV format an entry like Me, Myself & Irene would be presented as "Me, Myself & Irene". The quoting character might itself appear in a given entry, in which case it also needs to be escaped, often by doubling the character so that "" is interpreted as a literal " so that for a CSV format an entry like The movie "Me, Myself & Irene" would be presented as "The movie ""Me, Myself & Irene""". The Dialect.quoting, Dialect.quotechar, Dialect.escapechar, and Dialect.doublequote options in the csv library control the settings related to these considerations.

  • delimiter: a single-character string (this can be omitted or null).
  • doublequote: either true or false (this can be omitted or null).
  • escapechar a single-character string (this can be omitted or null).
  • lineterminator a string (this can be omitted or null). Note that this value currently has no effect on the csv library's parser.
  • quotechar: a single-character string (this can be omitted or null).
  • quoting: one of "QUOTE_ALL", "QUOTE_MINIMAL", "QUOTE_NONNUMERIC", or "QUOTE_NONE" (this can be omitted or null).
  • skipinitialwhitespace: either true or false (this can be omitted or null).

Excel worklog parsing

If your local worklogs are provided using a delimiter-separated values format such as CSV then you will need to provide a parse_excel section in the configuration file in order to specify how the data is parsed by jiraworklog. An example parse_excel section is shown below.

parse_excel:
  col_labels:
    description: "task"
    start:       "start"
    end:         "end"
    duration:    null
    tags:        "tags"
  col_formats:
    timezone:   "US/Eastern"
    delimiter2: ":"

The parse_delimited mapping has two required entries, col_labels and col_formats.

• col_labels: a mapping of entries specifying the meaning of the relevant columns in the source data. For example, if you had a column in your data named Start Time corresponding to the worlog entry start datetimes, then you would provide an entry start: "Start Time" in the mapping.

  Only 2 out of 3 of the columns corresponding to the worklogs start, end, and durations are required, although all three can be provided.

  • description: a string specifying the name of the column providing the description of the worklog.
  • start: a string specifying the name of the column providing the start datetime of the worklogs (this can be omitted or null).
  • end: a string specifying the name of the column providing the end datetime of the worklogs (this can be omitted or null).
  • duration: a string specifying the name of the column providing the duration of the worklogs (this can be omitted or null). The duration can be provided in a form like "2h 30m", which would correspond to a duration of 2 hours and 30 minutes (i.e. 150 minutes). The valid units of time are w for weeks, d for days, h for hours, m for minutes, and s for seconds. Not every unit of time need be included in a given worklog duration entry.
  • tags: a string specifying the name of the column providing the tags for the worklogs. Tags are the mechanism that are used to identify which Jira issue, if any, that a given worklog corresponds to. A worklog is allowed to have multiple tags, although only one tag can correspond to a Jira issue. If there are multiple tags then they are specified using a string that is separated by the delimiter2 character. For example, if delimiter2 is specified as ":" and a given tags entry is data processing:P9992-3 then the tags would be data processing and P9992-3.

• col_formats: a mapping of entries providing various column parsing information.

  • timezone a string specifying your timezone.

    The list of allowed timezone strings can be found by running either python -c 'import pytz, prettyprinter; prettyprinter.pprint(pytz.common_timezones)' to see the most common timezones or python -c 'import pytz, prettyprinter; prettyprinter.pprint(pytz.common_timezones)' to see all available timezones.

  • delimiter2 a single-character string specifying the character upon which to split the tags (this can be omitted or null). If delimiter2 is omitted or null then no tag splitting is performed.

Related software

This section is still under construction. Please feel free to post an issue or pull request suggesting any software that can be used to record worklog entries or interoperate with Jira worklogs.

• Microsoft Excel is a spreadsheet application that doesn't have specific support for worklogs but is perfectly amenable to manual entry of worklogs. The Excel data format is supported by jiraworklog.
• clockify is a web/desktop/mobile application that allows you to record worklog entries and create reports, among many other features. You can export your worklogs to CSV format which can then be uploaded to Jira via jiraworklog. Also note that there is a Clockify Jira plugin that integrates a clock in / clock out button into the Jira website such that when used the resulting worklog entry is registered both for Jira and for Clockify.

jiraworklog's Issues

Consider switching from pytz to dateutil / zoneinfo / tzdata

See pytz: The Fastest Footgun in the West. At the top of the datetime documentation there's also a link to zoneinfo, which itself has a link to tzdata.

Basic sematics proposal

Suppose we have the following collection of work time entries

entry 1
entry 2

that we provide as an input to our routines which has the effect of uploading the entries to Jira.
Then later we add another entry so that the entries look like this:

entry 1
entry 2
entry 3

If we want to submit this collection of entries to our routines then we want this to have the effect of uploading the entry 3 to Jira, but not entry 1 nor entry 2.

Actions that can occur

We have the following actions that can occur.

1. Local side
   1. Add entry
   2. Remove entry
   3. Update entry
2. Remote side
   1. Add entry
   2. Remove entry
   3. Update entry

Note that for our routines to be able to distinguish an update from a removal and addition, a given work log entry will have to have some kind of identifier. Some time clock applications will not provide us with such information, so we will need to think about whether we will want to have different behavior based on whether or not we have that information (in other words, even if we did have that information we could treat modifications the same as a removal and addition).

Add/remove/update a local entry

Let's call for now the entries that are already logged in to Jira the checked-in entries.

1. If we add/remove/update a local entry and the checked-in entries are unchanged locally and on the remote, then we should add the entry to the remote.
2. If we remove a local entry and other checked-in entries are unchanged locally and on the remote, then we should remove the corresponding entry on the remote.
3. If we update a local entry and other checked-in entries are unchanged locally and on the remote, then we should update the corresponding entry on the remote.

Add/remove/update an entry on the remote

If we add/remove/update an entry on the remote then ideally we would have a mechanism to update the local entry. However, most time clock applications will not have an programmatic way to make such an update, and I think we should support such applications. If we accept this as a fundamental limitation of our application, then we have the following options. Note that work log entries have a unique identifier so we always do have the ability to unambiguously identify what add/remove/update has occurred.

1. We could force the remote to align with the local view of the work log entries. This would amount to "throwing out" any changes that occur on the remote. This would by far be the most straightforward approach conceptually and to implement.
2. We could try to track any changes on the remote.
   1. Suppose an entry gets added on the remote. We could mostly just ignore it, but what happens if an entry gets added for the same time? We would probably in that case want to consider the new local entry to correspond to the remote entry.
   2. Suppose an entry gets removed from the remote.
      1. If the corresponding entry gets removed from the local view then we would probably consider the local and remote to be realigned with regards to the added entry.
      2. If the corresponding entry get updated in the local view then we have two situations depending on the time clock system that constructs our input data.
         1. If the time clock system does not have the ability to uniquely identify a given entry then an update amounts to a remove and then an add. Thus we are unable to distinguish this situation from a removal and unrelated addition, as opposed to a modification. So probably the best thing to do is to is to consider the removal as having realigned the local and remote with regards to the removed entry on the remote, and to then add the new entry to the remote.
         2. If the time clock system does have the ability to uniquely identify a given entry then we are able to identify an update in the local view. I think probably we still want to do the same thing as for the case where we can't identify the update: consider the removal as having realigned the local and remote with regards to the removed entry on the remote, and then add the modified entry to the remote as a new entry.
   3. Suppose an entry gets modified on the remote.
      1. If the corresponding entry gets updated from the local view then I think probably we will want to overwrite the modification on the remote.
      2. If the corresponding entry gets removed from the local view then I think probably we will want to remove the entry on the remote. Note that effectively we will be "discarding" any changes (prompt the user before performing?)

Do we want/need a persistent view of the local and/or remote work log entries?

1. If we force the remote to align with the local view of the work log entries, then we wouldn't need to keep a persistent local view (but could it be useful, despite not being strictly necessary?).
2. There are a few examples of situations where I think we might need a persistent view of the work log entries (this is not entended to be an exhaustive list)

• If an entry gets removed from the remote then we may not want to have it added back in by our routine. We would need to know about the existence of it to realize that it was a remote removal.
• If an entry gets modified on the remote then we may not want to have it added back in by our routine. We would have to know what it's original value was (or equivalently, which work log entry it corresponds to) to know which work log entry to not add to the remote.

Malformed entries

Open questions:

• What should we do with malformed local data? For example, if we have overlapping work log entries?
• If we have identical entries will this break any assumptions that we are making?
• Will Jira let us upload such entries?

Basic routines outline

Initial use outline

Push worklogs:

1. Fetch worklogs from the remote.
   1. Create an empty collection of checked-in worklogs.
   2. Existing worklogs on the remote are considered to be added entries.
2. Check which local entries correspond to remote entries and connect those.
3. Push the remaining local entries to the remote.
4. Add the remaining local entries to the checked-in worklogs.

General case outline

Push worklogs:

1. Fetch worklogs from the remote.
2. Compare the local view to the checked-in entries. Create a list of additions and removals.
3. Compare the remote view to the checked-in entries. Create a list of additions, removals, and updates.
4. Check modified remote entries. If there is a corresponding local removal then move them to the "added" remote category and remove the corresponding local removal entry.
5. Check which local "added" entries correspond to remote "added" entries and connect those.
6. Check which local "removed" entries correspond to remote "removed" entries and
7. Push remaining local "added" and "removed" entries to the remote.
8. Update the checked-in worklogs.

Initial error-testing checklist

Some examples of things to test for:

• error authenticating to Jira (special case WRT testing)
• config file doesn't exist
• config file not in the correct format
• worklogs file doesn't exist
• worklogs file not in the correct format
• checkedin file not in the correct format
• error reading from Jira
• error writing to Jira
• error writing to checkedin

User interface proposal

Packaging and installation

The routines will be presented as a Python package that can be downloaded by pip. The installation will include a an executable script that will serve as a command-line application. Thus the user installation process will roughly be:

1. Install Python
2. Install jira-worklog via pip
3. Ensure that the Python bin directory is on $PATH.

Application user interface

The main information that the application needs as inputs are the following.

1. The worklog entries. We will probably want to take this data either from standard input or from a file pointed to by e.g. a --file command-line argument.
2. The most recent checked-in state of the worklogs. This is something that would presumable be written by the application so we could potentially read from and write to a default location like e.g. ~/.config/jira-worklog/jira-worklog-state. Or maybe we could check the current working directory for a particular file name. We should probably also take command line arguments specifying non-default locations to read from and write to.
3. Possibly information on how to parse the worklog entries. We may be able to store configuration information for a set of commonly-used time clock applications. The kind of information we will need will be things like the following. Given the quantity of the information we will probably need a configuration file for this also, with the location specified via a command-line argument.
   1. Data format: CSV, TSV, JSON, etc.
   2. If we allow for multiple tags per work log entry then for "flat" formats like CSV we will need a second separator.
   3. Field key for: description, time start, time end, tags.
   4. Mapping of tags to Jira issues.

Given these considerations, a typical invocation might look something like the following (and where the checked-in worklog state and parsing information data is stored in some standard location).

jira-upload-worklog worklog-entries.csv

The fully specified version might look something like the following.

jira-upload-worklog --checked-in-entries=path/to/file --parse-config=path/to/other-file worklog-entries.csv

Considerations of the above approach

1. Relying on having a checked-in state file makes the ability to work on multiple machines more laborious. The user would have to share the checked-in state file across the different machines. Would it be possible to store the state on the Jira server somehow? Or perhaps we could consider provide support for reading and writing to remote locations like Dropbox or SSH etc.
2. The parsing configuration file should be able to support data from multiple time clock application systems. Maybe we allow for multiple named systems (and probably a field specifying a default system).

Outline of target functionality

Consider the following example CSV.

task,start,end,tags
Review sample size calculations document before 2021-01-05 meeting,2021-01-04 14:52,2021-01-04 16:53,P0053_07_rpp
Update effect size (power) calculations,2021-01-07 13:01,2021-01-07 14:54,P0053_07_rpp
Update effect size (power) calculations,2021-01-07 09:59,2021-01-07 11:45,P0053_07_rpp
Review effect size calculations Slack thread,2021-01-08 09:00,2021-01-08 09:30,P0053_07_rpp
Channel Slack conversation,2021-01-12 09:00,2021-01-12 09:33,P0053_07_rpp
Effort estimate for additional sensitivity analyses,2021-01-11 22:09,2021-01-11 22:55,P0053_04_pre_contract_work
Prepare Bayesian method proposal,2021-01-14 13:10,2021-01-14 13:30,P0053_12_meetings
Add project Git configuration file to specify 'pull as a rebase',2021-02-15 16:41,2021-02-15 17:15,P0053_07_rpp
Create a list of covariates to QC,2021-02-15 12:46,2021-02-15 13:00,P0053_14_create_cohort

Suppose this output is generated from some time clock application. We process the data upload the entries to Jira using the functionality provided by this library. Then some time passes and we generate some new work time entries, and we export the data again from our application. This new data may contain all of the original entries plus some new entries. If we provide the entirety of the newly exported data as the input to the library routines, the routines should be smart enough to upload only the new work time entries to Jira.

Data structures outline

Entries data structures

• Representation of local entries
  • A dict with keys given by issueId and value a dict with the following fields:
    • comment (i.e. the description)
    • started
    • timeSpentSeconds
• Representation of remote entries
  • Same as the representation of local entries but with the following added information:
    • id
    • updated
• Representation of checked-in entries
  • Same as the representation of remote entries

Added / updated / removed entries

Use the same representation as for the regular entries lists but add a level of depth after issueId level with added, updated, and removed keys.

Authentication walkthrough

To experiment with this package:

1. Get an Atlassian API token, unless you already have one.
   See here for details.
2. Ensure that the jira package is installed and on your search path.
3. Try out some code like the following.

from jira import JIRA

user = '[email protected]'          # your email address
apikey = 'XXXXXXXX'             # your API token
server = 'https://my.host.net'  # the URL up to the host name

jira = JIRA(server, basic_auth=(user,apikey) )

If you are able to authenticate then you can do something like the following.

from pprint import pprint  # only needed for interactive noodling around

# Load the following routine from `fetch_worklogs.py`
out = fetch_worklogs_remotedata(jira, ['P0053-4'])
pprint(out)

# This is what the raw data looks like
issue_p0053_04 = jira.issue('P0053-4')
worklogs_list = jira.worklogs(issue_p0053_04)
pprint(vars(worklogs_list[0]))