0
# Filters & Dashboards
1
2
Manage saved JQL filters and dashboard operations for organizing and sharing JIRA queries and visualizations.
3
4
## Capabilities
5
6
### Filter Management
7
8
Create, retrieve, and manage JQL filters for saved searches.
9
10
```python { .api }
11
def filter(self, id: str) -> Filter:
12
"""
13
Get a filter by ID.
14
15
Parameters:
16
- id: Filter ID
17
18
Returns:
19
Filter object
20
"""
21
22
def favourite_filters(self) -> list[Filter]:
23
"""
24
Get list of current user's favorite filters.
25
26
Returns:
27
List of Filter objects marked as favorites
28
"""
29
30
def create_filter(
31
self,
32
name: str = None,
33
description: str = None,
34
jql: str = None,
35
favourite: bool = None
36
) -> Filter:
37
"""
38
Create a new filter.
39
40
Parameters:
41
- name: Filter name
42
- description: Filter description
43
- jql: JQL query string
44
- favourite: Whether to mark as favorite
45
46
Returns:
47
Created Filter object
48
"""
49
50
def update_filter(
51
self,
52
filter_id: str,
53
name: str = None,
54
description: str = None,
55
jql: str = None,
56
favourite: bool = None
57
) -> Filter:
58
"""
59
Update an existing filter.
60
61
Parameters:
62
- filter_id: ID of filter to update
63
- name: New filter name
64
- description: New filter description
65
- jql: New JQL query string
66
- favourite: Whether to mark as favorite
67
68
Returns:
69
Updated Filter object
70
"""
71
```
72
73
Usage examples:
74
```python
75
# Get a specific filter
76
filter_obj = jira.filter('12345')
77
print(f"Filter: {filter_obj.name}")
78
print(f"JQL: {filter_obj.jql}")
79
print(f"Owner: {filter_obj.owner.displayName}")
80
81
# Get user's favorite filters
82
favorites = jira.favourite_filters()
83
for filter_obj in favorites:
84
print(f"Favorite: {filter_obj.name} - {filter_obj.jql}")
85
86
# Create a new filter
87
new_filter = jira.create_filter(
88
name="My High Priority Issues",
89
description="All high priority issues assigned to me",
90
jql="assignee = currentUser() AND priority = High",
91
favourite=True
92
)
93
print(f"Created filter: {new_filter.id}")
94
95
# Update an existing filter
96
updated_filter = jira.update_filter(
97
filter_id=new_filter.id,
98
name="My Critical Issues",
99
jql="assignee = currentUser() AND priority in (High, Highest)"
100
)
101
```
102
103
### Dashboard Management
104
105
Retrieve and manage JIRA dashboards for visualizing project data.
106
107
```python { .api }
108
def dashboards(
109
self,
110
filter: str = None,
111
startAt: int = 0,
112
maxResults: int = 20
113
) -> list[Dashboard]:
114
"""
115
Get dashboards visible to current user.
116
117
Parameters:
118
- filter: Dashboard name filter
119
- startAt: Starting index for pagination
120
- maxResults: Maximum number of results
121
122
Returns:
123
List of Dashboard objects
124
"""
125
126
def dashboard(self, id: str) -> Dashboard:
127
"""
128
Get a specific dashboard by ID.
129
130
Parameters:
131
- id: Dashboard ID
132
133
Returns:
134
Dashboard object
135
"""
136
```
137
138
Usage examples:
139
```python
140
# Get all dashboards
141
dashboards = jira.dashboards()
142
for dashboard in dashboards:
143
print(f"Dashboard: {dashboard.name}")
144
print(f"URL: {dashboard.view_url}")
145
146
# Search for specific dashboards
147
project_dashboards = jira.dashboards(filter="Project")
148
for dashboard in project_dashboards:
149
print(f"Project dashboard: {dashboard.name}")
150
151
# Get specific dashboard details
152
dashboard = jira.dashboard('12345')
153
print(f"Dashboard: {dashboard.name}")
154
print(f"Owner: {dashboard.owner.displayName}")
155
print(f"Favorite: {dashboard.favourite}")
156
```
157
158
## Filter Properties
159
160
Common properties available on Filter objects:
161
162
```python
163
filter_obj = jira.filter('12345')
164
165
# Basic properties
166
print(f"ID: {filter_obj.id}")
167
print(f"Name: {filter_obj.name}")
168
print(f"Description: {filter_obj.description}")
169
print(f"JQL: {filter_obj.jql}")
170
print(f"Favorite: {filter_obj.favourite}")
171
172
# Owner information
173
print(f"Owner: {filter_obj.owner.displayName}")
174
print(f"Owner Key: {filter_obj.owner.key}")
175
176
# URLs
177
print(f"View URL: {filter_obj.viewUrl}")
178
print(f"Search URL: {filter_obj.searchUrl}")
179
180
# Sharing and permissions
181
print(f"Share Permissions: {filter_obj.sharePermissions}")
182
print(f"Editable: {filter_obj.editable}")
183
184
# Subscription information (if available)
185
if hasattr(filter_obj, 'subscriptions'):
186
print(f"Subscriptions: {len(filter_obj.subscriptions)}")
187
```
188
189
## Dashboard Properties
190
191
Common properties available on Dashboard objects:
192
193
```python
194
dashboard = jira.dashboard('12345')
195
196
# Basic properties
197
print(f"ID: {dashboard.id}")
198
print(f"Name: {dashboard.name}")
199
print(f"Favorite: {dashboard.favourite}")
200
201
# Owner information
202
print(f"Owner: {dashboard.owner.displayName}")
203
204
# URLs
205
print(f"View URL: {dashboard.view_url}")
206
207
# Share permissions
208
print(f"Share Permissions: {dashboard.sharePermissions}")
209
print(f"Editable: {dashboard.editable}")
210
```
211
212
## Advanced Filter Usage
213
214
Common patterns for working with filters:
215
216
```python
217
# Create filter for team's work
218
team_filter = jira.create_filter(
219
name="Team Sprint Work",
220
description="Current sprint issues for development team",
221
jql='''
222
project = PROJ AND
223
sprint in openSprints() AND
224
assignee in (john.doe, jane.smith, bob.jones) AND
225
status != Done
226
ORDER BY priority DESC, created ASC
227
''',
228
favourite=True
229
)
230
231
# Use filter to get issues
232
issues = jira.search_issues(team_filter.jql)
233
print(f"Found {len(issues)} issues in current sprint")
234
235
# Update filter to add more conditions
236
jira.update_filter(
237
filter_id=team_filter.id,
238
jql=team_filter.jql + " AND labels not in (blocked, on-hold)"
239
)
240
241
# Share filter with team (requires additional permissions)
242
# This would typically be done through the JIRA UI or additional API calls
243
```
244
245
## Dashboard Integration
246
247
Using dashboards with filters:
248
249
```python
250
# Get user's dashboards
251
my_dashboards = jira.dashboards()
252
for dashboard in my_dashboards:
253
print(f"Dashboard: {dashboard.name}")
254
255
# Note: Gadget configuration and data would require
256
# additional API calls to the gadget endpoints
257
if dashboard.favourite:
258
print(f" ⭐ Favorite dashboard")
259
260
# Find dashboards containing specific filters
261
filter_name = "My Team Issues"
262
for dashboard in my_dashboards:
263
# In practice, you'd need to examine dashboard gadgets
264
# to find which filters they use
265
print(f"Checking dashboard: {dashboard.name}")
266
```
267
268
## Best Practices
269
270
When working with filters and dashboards:
271
272
```python
273
# Always check if filter exists before creating
274
def get_or_create_filter(jira_client, name, jql):
275
"""Get existing filter or create new one."""
276
favorites = jira_client.favourite_filters()
277
for filter_obj in favorites:
278
if filter_obj.name == name:
279
return filter_obj
280
281
# Create new filter if not found
282
return jira_client.create_filter(
283
name=name,
284
jql=jql,
285
favourite=True
286
)
287
288
# Use descriptive names and JQL
289
team_filter = get_or_create_filter(
290
jira,
291
"Backend Team - Current Sprint",
292
'''
293
project = BACKEND AND
294
sprint in openSprints() AND
295
component in ("API", "Database", "Services")
296
ORDER BY priority DESC
297
'''
298
)
299
300
# Validate JQL before creating filters
301
try:
302
test_results = jira.search_issues(jql_query, maxResults=1)
303
filter_obj = jira.create_filter(name="Test Filter", jql=jql_query)
304
except Exception as e:
305
print(f"Invalid JQL: {e}")
306
```