Package: task-jogger-jogseq
jogseqis a pluginjoggertask that provides an interactive program for synchronising Logseq and Jira.Check out thejoggerprojecton GitHuborread the documentationfor details onjogger.jogseqprovides support for the following, each of which iscovered in more detailbelow:Logging work to Jira as issue worklog entriesSummarising Logseq journals within a date rangeMore features TBAAlso be sure to check out theassumptions it makesand assess whether it suits your workflow.InstallationThe latest stable version ofjogseqcan be installed from PyPI:pip install task-jogger-jogseqThe following dependencies will also be installed:jogger: The underlying task running system thatjogseqis built on. See:https://github.com/oogles/task-jogger.jira: A Python API package for Jira. See:https://github.com/pycontribs/jira.Configurationjogseqcan be configured usingany compatible config filerecognised byjogger.The following settings are required:graph_path: The path to your Logseq graph. This should be the root directory of your graph, i.e. the directory containing thepagesandjournaldirectories.jira_url: The URL of your Jira instance. E.g.https://mycompany.atlassian.net.jira_user: Your Jira username/email address.The following optional settings are also available (seeFeaturesfor details on how and when to use them):jira_api_token: YourJira API token. If not specified, you will be prompted for it when the program is launched. While using this setting adds convenience by avoiding the prompt on every launch, it is less secure as it requires storing the token in plain text.duration_interval: The interval to round task durations to, in minutes. Defaults to5. Valid options are5and1.switching_cost: The estimated cost of context switching between tasks, in minutes. By default, no switching cost will be calculated. If specified, it should be a range that spans no more than 30 minutes, e.g.1-15. The switching cost per task will be based on that task’s duration - the longer the task, the higher the switching cost. Any task longer than an hour will use the maximum switching cost. To use a fixed switching cost per task, specify the same value for both ends of the range, e.g.5-5.target_duration: The target total duration for each daily journal, in minutes. The durations of all tasks in the journal, plus the calculated switching cost as per the above, will be compared to this figure and the difference, if any, will be reported. Defaults to420(7 hours).mark_done_when_logged: Whether to set worklog entries toDONEwhen they are marked as logged. Defaults totrue. Valid options aretrue,false,1, and0.min_duration_for_summary: The minimum duration, in minutes, that a Jira issue must have in order for it to be included in a journal summary. The duration is calculated as the sum of all worklog entries against the issue within the date range being summarised. A value of0disables this feature (allissues with worklogs during the summary period will be included in the summary). Defaults to0.The following is a sample config file showing example configurations for the above:[jogger:seq]
graph_path = /home/myuser/mygraph/

jira_url = https://mycompany.atlassian.net
jira_user = me@example.com
jira_api_token = <token_string>

duration_interval = 1
switching_cost = 1-15
target_duration = 450
mark_done_when_logged = false

min_duration_for_summary = 15NOTE: This assumes a task name ofseq, though any name can be used as long as it matches the name specified injog.py(see below).UsageOnce configured, create or update a relevantjog.pyfile to includeSeqTask:# jog.pyfromjogseq.tasksimportSeqTasktasks={'seq':SeqTask}Assuming a task name ofseq, as used in the above example, launch the program usingjog:$ jog seqThis will open an interactive menu, allowing you to select options by entering the corresponding number.Assumptionsjogseqmakes a number of assumptions about the structure of a Logseq journal, and the way you use it, in order to provide the featureset it does.For logging work to Jira, the following assumptions apply:Task blocks can use theNOW/LATERorTODO/DOINGworkflows, but will only be recognised as “worklog blocks” if this keyword is followed by a token looking like a Jira issue ID (one or more letters, a hyphen, then one or more numbers). It may optionally be followed by a colon, and using link syntax is supported. For example:# Valid
NOW ABC-123 Do something
NOW ABC-123: Do something
NOW [[ABC-123]]: Do something

# Invalid
NOW Do something (ABC-123)
NOW Do something #ABC-123
NOW Do something for [[ABC-123]]Worklog blocks (as identified per the above) cannot be nested within each other. This prevents ambiguity when determining the total duration of the worklog entry. Nesting worklogs under regular blocks is fine, as is nesting regular blocks under worklogs (they will be included in the worklog description). Ordinary task blocks (without a Jira ID) can also be nested under worklog blocks, but will NOT be included in the worklog description, and any time logged against them will NOT be included in the worklog duration.Time logged against any task blocks will be recognised and included in various duration calculations, but will only be logged to Jira if recorded against worklog blocks specifically (as identified per the above).FeaturesLogging workjogseqcan be used to create worklog entries against Jira issues that you track time against in Logseq. This feature works by examining a single day’s journal, identifying worklog blocks, parsing their content and total duration, and then logging that time to Jira.For a journal block to be considered a worklog valid for logging to Jira, it must:Use one of theNOW,LATER,TODO,DOING, orDONEkeywordsInclude a Jira issue ID immediately following the keywordHave some time logged against itIf any issues are encountered parsing any of these values, including being missing or invalid, an error will be reported and the worklog will not be loggable. Note that any blocks with a running timer (i.e. using theNOWorDOINGkeywords) will also report an error and not be loggable, as their final duration is unknown.The description used for a block’s Jira worklog entry will be comprised of the block’s direct content, as well as any child blocks nested under it, with the following considerations:The block’s keyword and Jira issue ID are excluded.Block properties are excluded.Any child blocks using task keywords (e.g.TODO,LATER,DONE, etc) are excluded.Any child blocks with theno-log::property are excluded. SeeIgnoring child blocks.Any Logseq heading syntax will be stripped. E.g. “### Did some work” will be logged as “Did some work”.Any Logseq link syntax will be stripped. E.g. “Meeting with [[Bob]]” will be logged as “Meeting with Bob”.When a worklog block is submitted to Jira, it will be given thelogged:: trueproperty. By default, it will also be set toDONE, but this is configurable via themark_done_when_loggedsetting. SeeConfiguration.Manual durationsTo aid in logging time thatisn’tcaptured by Logseq’s logbook functionality (perhaps because the task was only entered after time had already been spent on it, or the button to start the timer was just never pressed),jogseqsupports manually specifying a duration for a task. This is done by adding atime::property to the task block.Using thetime::property is perfectly compatible with using the logbook, and the two can be used together to capture all time spent on a task. Once atime::property is parsed byjogseq, it is converted to a logbook entry anyway (using fake timestamps starting from midnight of the journal’s date). As such, if the parsed journal is written back to the graph, thetime::property will be removed.If specified, thetime::property should use a human-readable duration shorthand, wherehrepresents hours andmrepresents minutes. The value can use a mix of both. Seconds are not supported. E.g.time:: 10m,time:: 2h,time:: 1h 30m.Duration roundingjogseqwill automatically round all task durations.By default, it rounds durations to five-minute intervals. Any duration more than 90 seconds into the next interval will be rounded up, otherwise it will be rounded down. This allows for consistency with reading and reporting logged time, and more closely aligns with how work would be logged manually, when not using a timer.However, if this is not desirable, it is also possible to configurejogseqto round durations to the nearest minute. This allows for higher accuracy if necessary. To do this, set theduration_intervalsetting to1. SeeConfiguration.In both configurations, durations of0are not rounded, but any duration greater than0and less than the chosen interval will always be rounded up, regardless of how close to0it is. Durations of0are not submitted to Jira.Target durationAfter parsing a journal,jogseqwill display the total duration of all tasks it found, and the difference between that total and a “target duration”. This can be used to see at a glance whether any additional time or tasks need to be entered into the journal before it is logged. By default, the target duration is 7 hours, but this can be configured via thetarget_durationsetting. SeeConfiguration.Context switching costIt is well-documented that context switching (i.e. switching between multiple tasks) is detrimental to productivity. It can also be difficult to assign a time cost to it, and track it reliably throughout the day such that it is reflected in a journal’s total duration.jogsequses a duration-based scale of context switching costs as a mechanism (albeit a simplistic and imperfect one) to help automatically track this extra time. A switching cost is calculatedper task, where shorter tasks have lower switching costs and longer tasks have higher ones, and the total is reported for the journal as a whole. The idea is that switching between multiple quick tasks involves less overhead than switching to or from longer tasks.The scale used to calculate switching costs can be any range of values, in minutes, that spans no more than 30 minutes in total. For example, it could be1-15,0-30, or45-75, but could not be1-60. To use the same switching cost for all tasks, specify the same value for both ends of the range, e.g.5-5. Any task with a duration over an hour will use the maximum switching cost.By default, the range is0-0, effectively disabling the feature. To enable it, specify a suitable range via theswitching_costsetting. SeeConfiguration.When a valid range is specified, an estimated overall context switching cost for the journal will always be calculated, reported, and included in the journal’s total duration. But it is not logged to Jira as part of individual worklog blocks. Rather, it will only be logged to Jira if a generic, “miscellaneous” worklog block is present in the journal. This block should be identified by having themisc:: trueproperty. There should only be one such block per journal. Only the first will be recognised, any additional miscellaneous blocks will be ignored and display a warning.Ignoring child blocksjogseqsupports ignoring specific child blocks of a worklog block, by adding theno-log::property to them. While usingno-log::trueis suggested, the property’s value is not important, merely its presence.This can be useful for excluding certain details from the Jira worklog, maybe because they are personal notes, would not be compatible, etc. Consider the following worklog block:- NOW ABC-123: Do a complicated thing
    - Step 1
    - Step 2
    - Step 3
    - Note to self: Never do this again.
      no-log:: trueThis would result in the following Jira worklog description:Do a complicated thing
- Step 1
- Step 2
- Step 3Note thatno-log::cannot be applied to a worklog block itself, only to its child blocks (it will simply be ignored). If a task block should not be logged to Jira, simply don’t give it a Jira issue ID.Repetitive tasksIf multiple worklog blocks would use the same description, it is possible to nest them under a common parent block and have them inherit their description from it. Each individual worklog block should just leave out a description - only specifying the Jira issue ID. This can be useful in cases where the same process is applied to multiple tasks, such as code review. For example:- Code review:
    - LATER ABC-123
    - LATER ABC-456
    - LATER ABC-789In this example, all three issues (ABC-123,ABC-456, andABC-789) will be have a worklog entry submitted to Jira with “Code review” as the worklog description. The parent block itself will not be logged. Any trailing colon in the parent block’s content will be stripped, but will otherwise be used verbatim.Summarising journalsjogseqcan be used to summarise work entered into journals over a given date range, to allow reviewing and reporting on work done over a period of time. By default, the date range is the last 7 days, including the current day, but program prompts allow altering the start and end dates of the range.Once the worklog entries within each included journal are processed, the output is written to the “Worklog Digest” page of your Logseq graph. This page is created if it does not already exist.Properties are used to annotate the page with some useful information:from-date: The start date of the summarised date range.to-date: The end date of the summarised date range.total-worklogs: The total number of worklog entries within the date range.total-duration: The total duration of all worklog entries within the date range.Note: Thetotal-worklogsandtotal-durationvalues will include worklog entries that wereexcludedfrom the summary itself, for any of the reasons covered below.The digest itself is written as a series of nested blocks, with a top-level block for each Jira issue, and child blocks for each worklog entry for that issue, including the date on which the worklog was entered. Top-level issue blocks are given adurationproperty totalling the durations of all worklog entries for the issue. Durations of individual worklog entries are not reported.To keep the digest as useful as possible, some issues or worklog entries may be excluded from it. Reasons for excluding a worklog entry may include:It has themiscproperty. Entries with this property are expected to be generic, “catch-all” entries that are not specific to any particular issue.It has no content. This is assumed to be because the task is simple and repetitive, and defined with theRepetitive tasksnotation.Whole issues may also be excluded from the digest, even if their individual worklog entries would otherwise have been included, for the following reasons:The sum of the duration of all worklog entries for the issue is less than themin_duration_for_summarysetting. This setting is disabled by default (all issues will be included, regardless of duration). However, it can be configured to exclude short tasks, if such tasks are considered irrelevant for review/reporting. SeeConfigurationfor configuringmin_duration_for_summary.