0
# Remote Links
1
2
Manage external links from JIRA issues to external applications, web resources, and other systems. Remote links allow you to connect JIRA issues with external tools and documentation.
3
4
## Capabilities
5
6
### Remote Link Operations
7
8
Create, retrieve, and manage remote links between JIRA issues and external resources.
9
10
```python { .api }
11
def remote_links(self, issue: Issue) -> list[RemoteLink]:
12
"""
13
Get all remote links for an issue.
14
15
Parameters:
16
- issue: Issue object or issue key
17
18
Returns:
19
List of RemoteLink objects
20
"""
21
22
def remote_link(self, issue: Issue, id: str) -> RemoteLink:
23
"""
24
Get a specific remote link by ID.
25
26
Parameters:
27
- issue: Issue object or issue key
28
- id: Remote link ID
29
30
Returns:
31
RemoteLink object
32
"""
33
34
def add_remote_link(
35
self,
36
issue: Issue,
37
destination: dict,
38
globalId: str = None,
39
application: dict = None,
40
relationship: str = None
41
) -> RemoteLink:
42
"""
43
Add a remote link to an external application.
44
45
Parameters:
46
- issue: Issue object or issue key
47
- destination: Link destination details (url, title, summary, icon)
48
- globalId: Global identifier for the link
49
- application: Application details (type, name)
50
- relationship: Relationship type to the issue
51
52
Returns:
53
Created RemoteLink object
54
"""
55
56
def add_simple_link(self, issue: Issue, object: dict) -> RemoteLink:
57
"""
58
Add a simple remote link to a web resource.
59
60
Parameters:
61
- issue: Issue object or issue key
62
- object: Link object with url, title, summary, and icon
63
64
Returns:
65
Created RemoteLink object
66
"""
67
```
68
69
Usage examples:
70
```python
71
# Get all remote links for an issue
72
issue = jira.issue('PROJ-123')
73
remote_links = jira.remote_links(issue)
74
for link in remote_links:
75
print(f"Link: {link.object['title']} -> {link.object['url']}")
76
77
# Get specific remote link
78
specific_link = jira.remote_link(issue, '10001')
79
print(f"Link title: {specific_link.object['title']}")
80
print(f"Link URL: {specific_link.object['url']}")
81
82
# Add a simple web link
83
simple_link = jira.add_simple_link(
84
issue=issue,
85
object={
86
'url': 'https://docs.example.com/feature-spec',
87
'title': 'Feature Specification',
88
'summary': 'Detailed specification document for this feature',
89
'icon': {
90
'url16x16': 'https://docs.example.com/favicon.ico',
91
'title': 'Documentation'
92
}
93
}
94
)
95
print(f"Created simple link: {simple_link.id}")
96
97
# Add a complex application link
98
app_link = jira.add_remote_link(
99
issue=issue,
100
destination={
101
'url': 'https://github.com/company/repo/pull/123',
102
'title': 'Pull Request #123',
103
'summary': 'Implementation of feature PROJ-123',
104
'icon': {
105
'url16x16': 'https://github.com/favicon.ico',
106
'title': 'GitHub'
107
}
108
},
109
application={
110
'type': 'com.github.integration',
111
'name': 'GitHub'
112
},
113
relationship='implements',
114
globalId='github:pr:company/repo:123'
115
)
116
print(f"Created application link: {app_link.id}")
117
```
118
119
### Link Management
120
121
Remove and update remote links.
122
123
```python { .api }
124
def delete_remote_link(self, issue: Issue, id: str) -> None:
125
"""
126
Delete a remote link by ID.
127
128
Parameters:
129
- issue: Issue object or issue key
130
- id: Remote link ID to delete
131
"""
132
133
def update_remote_link(
134
self,
135
issue: Issue,
136
id: str,
137
object: dict,
138
globalId: str = None,
139
application: dict = None,
140
relationship: str = None
141
) -> RemoteLink:
142
"""
143
Update an existing remote link.
144
145
Parameters:
146
- issue: Issue object or issue key
147
- id: Remote link ID to update
148
- object: Updated link object details
149
- globalId: Updated global identifier
150
- application: Updated application details
151
- relationship: Updated relationship type
152
153
Returns:
154
Updated RemoteLink object
155
"""
156
```
157
158
Usage examples:
159
```python
160
# Delete a remote link
161
jira.delete_remote_link(issue, '10001')
162
print("Remote link deleted")
163
164
# Update remote link (if supported by JIRA version)
165
try:
166
updated_link = jira.update_remote_link(
167
issue=issue,
168
id='10002',
169
object={
170
'url': 'https://updated-docs.example.com/feature-spec',
171
'title': 'Updated Feature Specification',
172
'summary': 'Updated specification with new requirements'
173
}
174
)
175
print(f"Updated link: {updated_link.id}")
176
except AttributeError:
177
print("Update not supported in this JIRA version")
178
```
179
180
## Remote Link Types
181
182
### Simple Web Links
183
184
Basic links to web resources:
185
186
```python
187
# Documentation link
188
doc_link = jira.add_simple_link(
189
issue='PROJ-123',
190
object={
191
'url': 'https://confluence.company.com/display/PROJ/Requirements',
192
'title': 'Requirements Document',
193
'summary': 'Detailed requirements for PROJ-123',
194
'icon': {
195
'url16x16': 'https://confluence.company.com/favicon.ico',
196
'title': 'Confluence'
197
}
198
}
199
)
200
201
# Design mockup link
202
design_link = jira.add_simple_link(
203
issue='PROJ-124',
204
object={
205
'url': 'https://figma.com/file/ABC123/Feature-Design',
206
'title': 'UI Design Mockup',
207
'summary': 'User interface design for the new feature',
208
'icon': {
209
'url16x16': 'https://figma.com/favicon.ico',
210
'title': 'Figma'
211
}
212
}
213
)
214
```
215
216
### Application Integration Links
217
218
Links with application context:
219
220
```python
221
# GitHub pull request
222
github_pr = jira.add_remote_link(
223
issue='PROJ-125',
224
destination={
225
'url': 'https://github.com/company/repo/pull/456',
226
'title': 'Fix authentication bug',
227
'summary': 'Pull request to resolve authentication issues',
228
'icon': {
229
'url16x16': 'https://github.com/favicon.ico',
230
'title': 'GitHub'
231
}
232
},
233
application={
234
'type': 'com.github.integration',
235
'name': 'GitHub for JIRA'
236
},
237
globalId='github:pr:company/repo:456',
238
relationship='fixes'
239
)
240
241
# Bitbucket commit
242
bitbucket_commit = jira.add_remote_link(
243
issue='PROJ-126',
244
destination={
245
'url': 'https://bitbucket.org/company/repo/commits/abc123def456',
246
'title': 'Implement feature PROJ-126',
247
'summary': 'Initial implementation of the requested feature',
248
'icon': {
249
'url16x16': 'https://bitbucket.org/favicon.ico',
250
'title': 'Bitbucket'
251
}
252
},
253
application={
254
'type': 'com.atlassian.bitbucket',
255
'name': 'Bitbucket'
256
},
257
globalId='bitbucket:commit:company/repo:abc123def456',
258
relationship='implements'
259
)
260
```
261
262
## Remote Link Properties
263
264
Common properties available on RemoteLink objects:
265
266
```python
267
remote_link = jira.remote_link('PROJ-123', '10001')
268
269
# Basic properties
270
print(f"ID: {remote_link.id}")
271
print(f"Self URL: {remote_link.self}")
272
273
# Object properties (the actual link)
274
link_obj = remote_link.object
275
print(f"Title: {link_obj['title']}")
276
print(f"URL: {link_obj['url']}")
277
print(f"Summary: {link_obj.get('summary', 'No summary')}")
278
279
# Icon information
280
if 'icon' in link_obj:
281
icon = link_obj['icon']
282
print(f"Icon URL: {icon.get('url16x16', 'No icon')}")
283
print(f"Icon Title: {icon.get('title', 'No title')}")
284
285
# Application information (if present)
286
if hasattr(remote_link, 'application'):
287
app = remote_link.application
288
print(f"Application Type: {app.get('type', 'Unknown')}")
289
print(f"Application Name: {app.get('name', 'Unknown')}")
290
291
# Global ID (if present)
292
if hasattr(remote_link, 'globalId'):
293
print(f"Global ID: {remote_link.globalId}")
294
295
# Relationship (if present)
296
if hasattr(remote_link, 'relationship'):
297
print(f"Relationship: {remote_link.relationship}")
298
```
299
300
## Bulk Remote Link Operations
301
302
Working with multiple remote links:
303
304
```python
305
def add_documentation_links(jira_client, issue_key, doc_links):
306
"""Add multiple documentation links to an issue."""
307
issue = jira_client.issue(issue_key)
308
created_links = []
309
310
for doc in doc_links:
311
try:
312
link = jira_client.add_simple_link(
313
issue=issue,
314
object={
315
'url': doc['url'],
316
'title': doc['title'],
317
'summary': doc.get('summary', ''),
318
'icon': doc.get('icon', {
319
'url16x16': 'https://example.com/doc-icon.png',
320
'title': 'Documentation'
321
})
322
}
323
)
324
created_links.append(link)
325
print(f"✓ Added link: {doc['title']}")
326
except Exception as e:
327
print(f"✗ Failed to add {doc['title']}: {e}")
328
329
return created_links
330
331
# Example usage
332
documentation_links = [
333
{
334
'url': 'https://docs.company.com/api/v1/auth',
335
'title': 'Authentication API Documentation',
336
'summary': 'Details on how to authenticate with the API'
337
},
338
{
339
'url': 'https://confluence.company.com/display/DEV/Setup',
340
'title': 'Development Setup Guide',
341
'summary': 'How to set up the development environment'
342
},
343
{
344
'url': 'https://wiki.company.com/Testing',
345
'title': 'Testing Guidelines',
346
'summary': 'Best practices for testing this feature'
347
}
348
]
349
350
created_links = add_documentation_links(jira, 'PROJ-127', documentation_links)
351
print(f"Created {len(created_links)} documentation links")
352
```
353
354
## Integration Examples
355
356
### GitHub Integration
357
358
```python
359
def link_github_pr(jira_client, issue_key, repo, pr_number):
360
"""Link a GitHub pull request to a JIRA issue."""
361
pr_url = f"https://github.com/{repo}/pull/{pr_number}"
362
363
# First, you might fetch PR details from GitHub API
364
# This is a simplified example
365
pr_title = f"Pull Request #{pr_number}"
366
367
return jira_client.add_remote_link(
368
issue=issue_key,
369
destination={
370
'url': pr_url,
371
'title': pr_title,
372
'summary': f'GitHub pull request for {issue_key}',
373
'icon': {
374
'url16x16': 'https://github.com/favicon.ico',
375
'title': 'GitHub'
376
}
377
},
378
application={
379
'type': 'com.github.integration',
380
'name': 'GitHub'
381
},
382
globalId=f'github:pr:{repo}:{pr_number}',
383
relationship='implements'
384
)
385
386
# Link PR to issue
387
github_link = link_github_pr(jira, 'PROJ-128', 'company/backend', 789)
388
print(f"Linked GitHub PR: {github_link.id}")
389
```
390
391
### Confluence Integration
392
393
```python
394
def link_confluence_page(jira_client, issue_key, page_url, page_title):
395
"""Link a Confluence page to a JIRA issue."""
396
return jira_client.add_simple_link(
397
issue=issue_key,
398
object={
399
'url': page_url,
400
'title': page_title,
401
'summary': f'Confluence documentation for {issue_key}',
402
'icon': {
403
'url16x16': 'https://confluence.atlassian.com/favicon.ico',
404
'title': 'Confluence'
405
}
406
}
407
)
408
409
# Link Confluence page
410
confluence_link = link_confluence_page(
411
jira,
412
'PROJ-129',
413
'https://company.atlassian.net/wiki/spaces/DEV/pages/12345/Feature+Spec',
414
'Feature Specification - PROJ-129'
415
)
416
```
417
418
## Best Practices
419
420
When working with remote links:
421
422
```python
423
# Check existing links before adding
424
def add_unique_remote_link(jira_client, issue_key, link_url, link_title):
425
"""Add remote link only if URL doesn't already exist."""
426
issue = jira_client.issue(issue_key)
427
existing_links = jira_client.remote_links(issue)
428
429
# Check if URL already exists
430
for link in existing_links:
431
if link.object.get('url') == link_url:
432
print(f"Link already exists: {link_title}")
433
return link
434
435
# Add new link
436
return jira_client.add_simple_link(
437
issue=issue,
438
object={
439
'url': link_url,
440
'title': link_title,
441
'summary': f'External link for {issue_key}'
442
}
443
)
444
445
# Clean up broken links
446
def cleanup_broken_links(jira_client, issue_key):
447
"""Remove links that return 404 or are otherwise broken."""
448
import requests
449
450
issue = jira_client.issue(issue_key)
451
remote_links = jira_client.remote_links(issue)
452
453
for link in remote_links:
454
url = link.object.get('url')
455
if url:
456
try:
457
response = requests.head(url, timeout=10)
458
if response.status_code >= 400:
459
print(f"Removing broken link: {link.object['title']}")
460
jira_client.delete_remote_link(issue, link.id)
461
except requests.RequestException:
462
print(f"Could not check link: {link.object['title']}")
463
464
# Example usage
465
add_unique_remote_link(
466
jira,
467
'PROJ-130',
468
'https://docs.example.com/feature',
469
'Feature Documentation'
470
)
471
```