CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-jira

Python library for interacting with JIRA via REST APIs.

—

Pending
Overview
Eval results
Files

worklogs.mddocs/

Worklogs & Time Tracking

Work logging and time tracking functionality for issues. This includes recording time spent, adjusting estimates, and managing work log entries with various time adjustment options.

Capabilities

Worklog Management

Operations for managing work log entries on issues.

def worklogs(self, issue: Issue) -> list[Worklog]:
    """
    Get all worklogs for an issue.
    
    Parameters:
    - issue: Issue object or issue key
    
    Returns:
    List of Worklog objects
    """

def worklog(self, issue: Issue, id: str) -> Worklog:
    """
    Get a specific worklog by ID.
    
    Parameters:
    - issue: Issue object or issue key
    - id: Worklog ID
    
    Returns:
    Worklog object
    """

def add_worklog(
    self,
    issue: Issue,
    timeSpent: str = None,
    timeSpentSeconds: int = None,
    adjustEstimate: str = None,
    newEstimate: str = None,
    reduceBy: str = None,
    comment: str = None,
    started: str = None,
    user: str = None
) -> Worklog:
    """
    Add a worklog entry to an issue.
    
    Parameters:
    - issue: Issue object or issue key
    - timeSpent: Time spent in JIRA format (e.g., '2h 30m', '1d 4h')
    - timeSpentSeconds: Time spent in seconds (alternative to timeSpent)
    - adjustEstimate: How to adjust the remaining estimate
      - 'new': Set new estimate (requires newEstimate)
      - 'leave': Don't change estimate
      - 'manual': Reduce by specific amount (requires reduceBy)
      - 'auto': Reduce estimate by time spent (default)
    - newEstimate: New remaining estimate when adjustEstimate='new'
    - reduceBy: Amount to reduce estimate when adjustEstimate='manual'
    - comment: Comment describing the work performed
    - started: When work started (ISO 8601 format or JIRA date format)
    - user: Username of the person who did the work
    
    Returns:
    Created Worklog object
    """

Usage examples:

# Get all worklogs for an issue
issue = jira.issue('PROJ-123')
worklogs = jira.worklogs(issue)
for worklog in worklogs:
    print(f"Author: {worklog.author.displayName}")
    print(f"Time spent: {worklog.timeSpent}")
    print(f"Started: {worklog.started}")
    print(f"Comment: {worklog.comment}")
    print("---")

# Add simple worklog
worklog = jira.add_worklog(
    issue='PROJ-123',
    timeSpent='2h 30m',
    comment='Fixed authentication bug'
)
print(f"Added worklog: {worklog.id}")

# Add worklog with specific start time
from datetime import datetime
start_time = datetime.now().isoformat()
worklog = jira.add_worklog(
    issue='PROJ-123',
    timeSpent='4h',
    comment='Implemented new feature',
    started=start_time
)

# Add worklog with time in seconds
worklog = jira.add_worklog(
    issue='PROJ-123',
    timeSpentSeconds=7200,  # 2 hours
    comment='Code review and testing'
)

# Get specific worklog
worklog = jira.worklog('PROJ-123', worklog.id)
print(f"Time spent: {worklog.timeSpent}")
print(f"Time in seconds: {worklog.timeSpentSeconds}")

Time Estimate Adjustments

Control how adding worklogs affects the remaining time estimate.

# Auto-adjust estimate (default behavior)
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='3h',
    comment='Development work',
    adjustEstimate='auto'  # Reduces remaining estimate by 3h
)

# Set new remaining estimate
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='2h',
    comment='Bug fixing',
    adjustEstimate='new',
    newEstimate='4h'  # Set remaining estimate to 4h
)

# Manually reduce estimate by specific amount
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='1h',
    comment='Documentation',
    adjustEstimate='manual',
    reduceBy='30m'  # Reduce remaining estimate by 30 minutes
)

# Leave estimate unchanged
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='1h 30m',
    comment='Meeting and planning',
    adjustEstimate='leave'  # Don't change remaining estimate
)

Worklog Operations

Worklogs can be updated and deleted through the Worklog resource object.

# Delete a worklog
worklog = jira.worklog('PROJ-123', '12345')
worklog.delete()

# Delete worklog with estimate adjustment
worklog.delete(
    adjustEstimate='new',
    newEstimate='8h'
)

# Delete worklog with manual estimate adjustment
worklog.delete(
    adjustEstimate='manual',
    increaseBy='2h'  # Increase remaining estimate by 2h
)

Advanced Worklog Examples

Complex worklog scenarios and bulk operations.

# Log work for different users (requires admin permissions)
team_work = [
    {'user': 'john.doe', 'time': '4h', 'task': 'Frontend development'},
    {'user': 'jane.smith', 'time': '3h', 'task': 'Backend API'},
    {'user': 'bob.wilson', 'time': '2h', 'task': 'Testing and QA'}
]

for work in team_work:
    jira.add_worklog(
        issue='PROJ-123',
        timeSpent=work['time'],
        comment=work['task'],
        user=work['user']
    )

# Log work with specific dates
import datetime

# Log work for yesterday
yesterday = (datetime.datetime.now() - datetime.timedelta(days=1))
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='6h',
    comment='Development work from yesterday',
    started=yesterday.strftime('%Y-%m-%dT%H:%M:%S.000+0000')
)

# Log work for a specific date and time
specific_date = datetime.datetime(2024, 3, 15, 9, 0, 0)
jira.add_worklog(
    issue='PROJ-123',
    timeSpent='8h',
    comment='Full day of development',
    started=specific_date.strftime('%Y-%m-%dT%H:%M:%S.000+0000')
)

Time Format Examples

JIRA supports various time formats for logging work:

Standard Time Formats

# Hours and minutes
jira.add_worklog('PROJ-123', timeSpent='2h 30m')
jira.add_worklog('PROJ-123', timeSpent='1h 15m')

# Days and hours
jira.add_worklog('PROJ-123', timeSpent='1d 4h')
jira.add_worklog('PROJ-123', timeSpent='2d')

# Weeks, days, hours, minutes
jira.add_worklog('PROJ-123', timeSpent='1w 2d 3h 30m')

# Just hours
jira.add_worklog('PROJ-123', timeSpent='5h')

# Just minutes
jira.add_worklog('PROJ-123', timeSpent='45m')

Time in Seconds

# Alternative to time format strings
jira.add_worklog('PROJ-123', timeSpentSeconds=3600)    # 1 hour
jira.add_worklog('PROJ-123', timeSpentSeconds=9000)    # 2.5 hours
jira.add_worklog('PROJ-123', timeSpentSeconds=28800)   # 8 hours (1 day)

Worklog Properties

Common properties available in Worklog objects:

worklog = jira.worklog('PROJ-123', '12345')

# Basic properties
print(f"ID: {worklog.id}")
print(f"Author: {worklog.author.displayName}")
print(f"Time Spent: {worklog.timeSpent}")
print(f"Time in Seconds: {worklog.timeSpentSeconds}")
print(f"Comment: {worklog.comment}")
print(f"Created: {worklog.created}")
print(f"Updated: {worklog.updated}")
print(f"Started: {worklog.started}")

# Check if worklog has visibility restrictions
if hasattr(worklog, 'visibility'):
    print(f"Visibility: {worklog.visibility}")

Time Tracking Reports

Generate time tracking reports using worklog data:

# Get time tracking summary for an issue
def get_time_summary(issue_key):
    issue = jira.issue(issue_key)
    worklogs = jira.worklogs(issue)
    
    total_seconds = sum(w.timeSpentSeconds for w in worklogs)
    total_hours = total_seconds / 3600
    
    # Get estimate information
    original_estimate = getattr(issue.fields, 'timeoriginalestimate', 0) or 0
    remaining_estimate = getattr(issue.fields, 'timeestimate', 0) or 0
    
    return {
        'issue': issue_key,
        'original_estimate_hours': original_estimate / 3600,
        'time_spent_hours': total_hours,
        'remaining_estimate_hours': remaining_estimate / 3600,
        'worklog_count': len(worklogs)
    }

# Generate report for multiple issues
issues = jira.search_issues('project = PROJ AND worklogDate >= -30d')
for issue in issues:
    summary = get_time_summary(issue.key)
    print(f"{summary['issue']}: {summary['time_spent_hours']:.1f}h logged")

Worklog Visibility

Control worklog visibility (requires appropriate permissions):

# Worklog visible to specific group
# Note: Visibility for worklogs may not be supported in all JIRA versions
worklog_data = {
    'timeSpent': '2h',
    'comment': 'Internal development work',
    'visibility': {
        'type': 'group',
        'value': 'developers'
    }
}

# This would need to be done via direct API call if not supported
# by the high-level add_worklog method

Estimate Adjustment Strategies

Choose the right estimate adjustment strategy based on your workflow:

Auto Adjustment (Recommended)

  • Automatically reduces remaining estimate by time logged
  • Good for most development workflows
  • Keeps estimates realistic

New Estimate

  • Sets a completely new remaining estimate
  • Useful when reassessing work after logging time
  • Good for course corrections

Manual Reduction

  • Reduces estimate by a specific amount
  • Useful when logged time doesn't directly correlate to progress
  • Good for research or investigation tasks

Leave Unchanged

  • Doesn't modify the remaining estimate
  • Useful for overhead activities like meetings
  • Good for time tracking without affecting estimates

Install with Tessl CLI

npx tessl i tessl/pypi-jira@2.0.2

docs

administration.md

agile-boards.md

client-setup.md

comments-attachments.md

filters-dashboards.md

index.md

issue-management.md

project-management.md

remote-links.md

service-desk.md

system-operations.md

user-management.md

worklogs.md

tile.json