0
# Worklogs & Time Tracking
1

2
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.
3

4
## Capabilities
5

6
### Worklog Management
7

8
Operations for managing work log entries on issues.
9

10
```python { .api }
11
def worklogs(self, issue: Issue) -> list[Worklog]:
12
    """
13
    Get all worklogs for an issue.
14
    
15
    Parameters:
16
    - issue: Issue object or issue key
17
    
18
    Returns:
19
    List of Worklog objects
20
    """
21

22
def worklog(self, issue: Issue, id: str) -> Worklog:
23
    """
24
    Get a specific worklog by ID.
25
    
26
    Parameters:
27
    - issue: Issue object or issue key
28
    - id: Worklog ID
29
    
30
    Returns:
31
    Worklog object
32
    """
33

34
def add_worklog(
35
    self,
36
    issue: Issue,
37
    timeSpent: str = None,
38
    timeSpentSeconds: int = None,
39
    adjustEstimate: str = None,
40
    newEstimate: str = None,
41
    reduceBy: str = None,
42
    comment: str = None,
43
    started: str = None,
44
    user: str = None
45
) -> Worklog:
46
    """
47
    Add a worklog entry to an issue.
48
    
49
    Parameters:
50
    - issue: Issue object or issue key
51
    - timeSpent: Time spent in JIRA format (e.g., '2h 30m', '1d 4h')
52
    - timeSpentSeconds: Time spent in seconds (alternative to timeSpent)
53
    - adjustEstimate: How to adjust the remaining estimate
54
      - 'new': Set new estimate (requires newEstimate)
55
      - 'leave': Don't change estimate
56
      - 'manual': Reduce by specific amount (requires reduceBy)
57
      - 'auto': Reduce estimate by time spent (default)
58
    - newEstimate: New remaining estimate when adjustEstimate='new'
59
    - reduceBy: Amount to reduce estimate when adjustEstimate='manual'
60
    - comment: Comment describing the work performed
61
    - started: When work started (ISO 8601 format or JIRA date format)
62
    - user: Username of the person who did the work
63
    
64
    Returns:
65
    Created Worklog object
66
    """
67
```
68

69
Usage examples:
70
```python
71
# Get all worklogs for an issue
72
issue = jira.issue('PROJ-123')
73
worklogs = jira.worklogs(issue)
74
for worklog in worklogs:
75
    print(f"Author: {worklog.author.displayName}")
76
    print(f"Time spent: {worklog.timeSpent}")
77
    print(f"Started: {worklog.started}")
78
    print(f"Comment: {worklog.comment}")
79
    print("---")
80

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

89
# Add worklog with specific start time
90
from datetime import datetime
91
start_time = datetime.now().isoformat()
92
worklog = jira.add_worklog(
93
    issue='PROJ-123',
94
    timeSpent='4h',
95
    comment='Implemented new feature',
96
    started=start_time
97
)
98

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

106
# Get specific worklog
107
worklog = jira.worklog('PROJ-123', worklog.id)
108
print(f"Time spent: {worklog.timeSpent}")
109
print(f"Time in seconds: {worklog.timeSpentSeconds}")
110
```
111

112
### Time Estimate Adjustments
113

114
Control how adding worklogs affects the remaining time estimate.
115

116
```python
117
# Auto-adjust estimate (default behavior)
118
jira.add_worklog(
119
    issue='PROJ-123',
120
    timeSpent='3h',
121
    comment='Development work',
122
    adjustEstimate='auto'  # Reduces remaining estimate by 3h
123
)
124

125
# Set new remaining estimate
126
jira.add_worklog(
127
    issue='PROJ-123',
128
    timeSpent='2h',
129
    comment='Bug fixing',
130
    adjustEstimate='new',
131
    newEstimate='4h'  # Set remaining estimate to 4h
132
)
133

134
# Manually reduce estimate by specific amount
135
jira.add_worklog(
136
    issue='PROJ-123',
137
    timeSpent='1h',
138
    comment='Documentation',
139
    adjustEstimate='manual',
140
    reduceBy='30m'  # Reduce remaining estimate by 30 minutes
141
)
142

143
# Leave estimate unchanged
144
jira.add_worklog(
145
    issue='PROJ-123',
146
    timeSpent='1h 30m',
147
    comment='Meeting and planning',
148
    adjustEstimate='leave'  # Don't change remaining estimate
149
)
150
```
151

152
### Worklog Operations
153

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

156
```python
157
# Delete a worklog
158
worklog = jira.worklog('PROJ-123', '12345')
159
worklog.delete()
160

161
# Delete worklog with estimate adjustment
162
worklog.delete(
163
    adjustEstimate='new',
164
    newEstimate='8h'
165
)
166

167
# Delete worklog with manual estimate adjustment
168
worklog.delete(
169
    adjustEstimate='manual',
170
    increaseBy='2h'  # Increase remaining estimate by 2h
171
)
172
```
173

174
### Advanced Worklog Examples
175

176
Complex worklog scenarios and bulk operations.
177

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

186
for work in team_work:
187
    jira.add_worklog(
188
        issue='PROJ-123',
189
        timeSpent=work['time'],
190
        comment=work['task'],
191
        user=work['user']
192
    )
193

194
# Log work with specific dates
195
import datetime
196

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

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

216
## Time Format Examples
217

218
JIRA supports various time formats for logging work:
219

220
### Standard Time Formats
221
```python
222
# Hours and minutes
223
jira.add_worklog('PROJ-123', timeSpent='2h 30m')
224
jira.add_worklog('PROJ-123', timeSpent='1h 15m')
225

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

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

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

236
# Just minutes
237
jira.add_worklog('PROJ-123', timeSpent='45m')
238
```
239

240
### Time in Seconds
241
```python
242
# Alternative to time format strings
243
jira.add_worklog('PROJ-123', timeSpentSeconds=3600)    # 1 hour
244
jira.add_worklog('PROJ-123', timeSpentSeconds=9000)    # 2.5 hours
245
jira.add_worklog('PROJ-123', timeSpentSeconds=28800)   # 8 hours (1 day)
246
```
247

248
## Worklog Properties
249

250
Common properties available in Worklog objects:
251

252
```python
253
worklog = jira.worklog('PROJ-123', '12345')
254

255
# Basic properties
256
print(f"ID: {worklog.id}")
257
print(f"Author: {worklog.author.displayName}")
258
print(f"Time Spent: {worklog.timeSpent}")
259
print(f"Time in Seconds: {worklog.timeSpentSeconds}")
260
print(f"Comment: {worklog.comment}")
261
print(f"Created: {worklog.created}")
262
print(f"Updated: {worklog.updated}")
263
print(f"Started: {worklog.started}")
264

265
# Check if worklog has visibility restrictions
266
if hasattr(worklog, 'visibility'):
267
    print(f"Visibility: {worklog.visibility}")
268
```
269

270
## Time Tracking Reports
271

272
Generate time tracking reports using worklog data:
273

274
```python
275
# Get time tracking summary for an issue
276
def get_time_summary(issue_key):
277
    issue = jira.issue(issue_key)
278
    worklogs = jira.worklogs(issue)
279
    
280
    total_seconds = sum(w.timeSpentSeconds for w in worklogs)
281
    total_hours = total_seconds / 3600
282
    
283
    # Get estimate information
284
    original_estimate = getattr(issue.fields, 'timeoriginalestimate', 0) or 0
285
    remaining_estimate = getattr(issue.fields, 'timeestimate', 0) or 0
286
    
287
    return {
288
        'issue': issue_key,
289
        'original_estimate_hours': original_estimate / 3600,
290
        'time_spent_hours': total_hours,
291
        'remaining_estimate_hours': remaining_estimate / 3600,
292
        'worklog_count': len(worklogs)
293
    }
294

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

302
## Worklog Visibility
303

304
Control worklog visibility (requires appropriate permissions):
305

306
```python
307
# Worklog visible to specific group
308
# Note: Visibility for worklogs may not be supported in all JIRA versions
309
worklog_data = {
310
    'timeSpent': '2h',
311
    'comment': 'Internal development work',
312
    'visibility': {
313
        'type': 'group',
314
        'value': 'developers'
315
    }
316
}
317

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

322
## Estimate Adjustment Strategies
323

324
Choose the right estimate adjustment strategy based on your workflow:
325

326
### Auto Adjustment (Recommended)
327
- Automatically reduces remaining estimate by time logged
328
- Good for most development workflows
329
- Keeps estimates realistic
330

331
### New Estimate
332
- Sets a completely new remaining estimate
333
- Useful when reassessing work after logging time
334
- Good for course corrections
335

336
### Manual Reduction
337
- Reduces estimate by a specific amount
338
- Useful when logged time doesn't directly correlate to progress
339
- Good for research or investigation tasks
340

341
### Leave Unchanged
342
- Doesn't modify the remaining estimate
343
- Useful for overhead activities like meetings
344
- Good for time tracking without affecting estimates