0
# Apache Airflow Providers Jira (Deprecated)
1

2
A deprecated Apache Airflow provider package that enables integration with Atlassian Jira ticketing systems. This package serves as a compatibility layer that re-exports components from the newer `apache-airflow-providers-atlassian-jira` package.
3

4
**⚠️ IMPORTANT**: This package is deprecated as of version 3.1.0. Users should migrate to `apache-airflow-providers-atlassian-jira` for continued support and updates.
5

6
## Package Information
7

8
- **Package Name**: apache-airflow-providers-jira
9
- **Language**: Python
10
- **Installation**: `pip install apache-airflow-providers-jira`
11
- **Dependencies**: 
12
  - `apache-airflow>=2.2.0`
13
  - `apache-airflow-providers-atlassian-jira` (replacement package)
14

15
## Core Imports
16

17
```python
18
# Deprecated imports (still work but show warnings)
19
from airflow.providers.jira.hooks.jira import JiraHook
20
from airflow.providers.jira.operators.jira import JiraOperator
21
from airflow.providers.jira.sensors.jira import JiraSensor, JiraTicketSensor
22

23
# Direct package import (deprecated)
24
import airflow.providers.jira
25
```
26

27
## Basic Usage
28

29
```python
30
import warnings
31
from airflow.providers.jira.hooks.jira import JiraHook
32
from airflow.providers.jira.operators.jira import JiraOperator
33
from airflow.providers.jira.sensors.jira import JiraSensor
34

35
# Usage will trigger deprecation warnings
36
with warnings.catch_warnings():
37
    warnings.simplefilter("ignore", DeprecationWarning)
38
    
39
    # Create a Jira hook connection
40
    jira_hook = JiraHook(jira_conn_id='jira_default')
41
    
42
    # Use in a DAG operator
43
    jira_operator = JiraOperator(
44
        task_id='create_jira_ticket',
45
        jira_method='create_issue',
46
        jira_method_args={'fields': {'project': {'key': 'TEST'}, 'summary': 'Test Issue'}},
47
        dag=dag
48
    )
49
    
50
    # Use JiraSensor (generic sensor)
51
    jira_sensor = JiraSensor(
52
        task_id='check_jira_issue',
53
        jira_conn_id='jira_default',
54
        method_name='issue',
55
        method_params={'id': 'TEST-123', 'fields': 'status'},
56
        dag=dag
57
    )
58
    
59
    # Use JiraTicketSensor (specific ticket monitoring)
60
    jira_ticket_sensor = JiraTicketSensor(
61
        task_id='wait_for_jira_ticket',
62
        jira_conn_id='jira_default',
63
        ticket_id='TEST-123',
64
        field='status',
65
        expected_value='Done',
66
        dag=dag
67
    )
68
```
69

70
**Recommended Migration**:
71

72
```python
73
# New recommended imports
74
from airflow.providers.atlassian.jira.hooks.jira import JiraHook
75
from airflow.providers.atlassian.jira.operators.jira import JiraOperator
76
from airflow.providers.atlassian.jira.sensors.jira import JiraSensor, JiraTicketSensor
77
```
78

79
## Capabilities
80

81
### Jira Connectivity
82

83
Provides hook for connecting to Jira APIs with authentication and basic API interaction capabilities.
84

85
```python { .api }
86
class JiraHook(BaseHook):
87
    """
88
    Re-exported from airflow.providers.atlassian.jira.hooks.jira.JiraHook
89
    
90
    Jira interaction hook, a wrapper around JIRA Python SDK.
91
    Deprecated: Use airflow.providers.atlassian.jira.hooks.jira.JiraHook instead.
92
    
93
    Args:
94
        jira_conn_id (str): Reference to a pre-defined Jira Connection (default: 'jira_default')
95
        proxies (Any | None): Proxy configuration for JIRA client
96
    """
97
    
98
    default_conn_name: str = 'jira_default'
99
    conn_type: str = "jira"
100
    conn_name_attr: str = "jira_conn_id"
101
    hook_name: str = "JIRA"
102
    
103
    def __init__(self, jira_conn_id: str = default_conn_name, proxies: Any | None = None) -> None: ...
104
    
105
    def get_conn(self) -> JIRA:
106
        """
107
        Returns connection to JIRA client.
108
        
109
        Returns:
110
            JIRA: Authenticated JIRA client instance
111
            
112
        Raises:
113
            AirflowException: If connection cannot be established
114
        """
115
```
116

117
### Jira Operations
118

119
Provides operator for performing Jira operations within Airflow DAGs, including creating, updating, and managing Jira issues.
120

121
```python { .api }
122
class JiraOperator(BaseOperator):
123
    """
124
    Re-exported from airflow.providers.atlassian.jira.operators.jira.JiraOperator
125
    
126
    JiraOperator to interact and perform action on Jira issue tracking system.
127
    This operator is designed to use Jira Python SDK: http://jira.readthedocs.io
128
    Deprecated: Use airflow.providers.atlassian.jira.operators.jira.JiraOperator instead.
129
    
130
    Args:
131
        jira_conn_id (str): Reference to a pre-defined Jira Connection (default: 'jira_default')
132
        jira_method (str): Method name from Jira Python SDK to be called
133
        jira_method_args (dict | None): Required method parameters for the jira_method (templated)
134
        result_processor (Callable | None): Function to further process the response from Jira
135
        get_jira_resource_method (Callable | None): Function or operator to get jira resource
136
                                                   on which the provided jira_method will be executed
137
    """
138
    
139
    template_fields: Sequence[str] = ("jira_method_args",)
140
    
141
    def __init__(
142
        self,
143
        *,
144
        jira_method: str,
145
        jira_conn_id: str = 'jira_default',
146
        jira_method_args: dict | None = None,
147
        result_processor: Callable | None = None,
148
        get_jira_resource_method: Callable | None = None,
149
        **kwargs,
150
    ) -> None: ...
151
    
152
    def execute(self, context: Context) -> Any:
153
        """
154
        Execute the Jira method with provided arguments.
155
        
156
        Args:
157
            context: Airflow task context
158
            
159
        Returns:
160
            Any: Result from Jira method call, optionally processed by result_processor
161
            
162
        Raises:
163
            AirflowException: If Jira operation fails
164
        """
165
```
166

167
### Jira Monitoring
168

169
Provides sensors for polling Jira issue states and monitoring specific ticket conditions in workflow orchestration.
170

171
```python { .api }
172
class JiraSensor(BaseSensorOperator):
173
    """
174
    Re-exported from airflow.providers.atlassian.jira.sensors.jira.JiraSensor
175
    
176
    Monitors a jira ticket for any change.
177
    Deprecated: Use airflow.providers.atlassian.jira.sensors.jira.JiraSensor instead.
178
    
179
    Args:
180
        jira_conn_id (str): Reference to a pre-defined Jira Connection (default: 'jira_default')
181
        method_name (str): Method name from jira-python-sdk to be executed
182
        method_params (dict | None): Parameters for the method method_name
183
        result_processor (Callable | None): Function that returns boolean and acts as a sensor response
184
    """
185
    
186
    def __init__(
187
        self,
188
        *,
189
        method_name: str,
190
        jira_conn_id: str = 'jira_default',
191
        method_params: dict | None = None,
192
        result_processor: Callable | None = None,
193
        **kwargs,
194
    ) -> None: ...
195
    
196
    def poke(self, context: Context) -> Any:
197
        """
198
        Poke method to check Jira resource state.
199
        
200
        Args:
201
            context: Airflow task context
202
            
203
        Returns:
204
            Any: Result from Jira method call, optionally processed by result_processor
205
        """
206

207
class JiraTicketSensor(JiraSensor):
208
    """
209
    Re-exported from airflow.providers.atlassian.jira.sensors.jira.JiraTicketSensor
210
    
211
    Monitors a jira ticket for given change in terms of function.
212
    Deprecated: Use airflow.providers.atlassian.jira.sensors.jira.JiraTicketSensor instead.
213
    
214
    Args:
215
        jira_conn_id (str): Reference to a pre-defined Jira Connection (default: 'jira_default')
216
        ticket_id (str | None): ID of the ticket to be monitored
217
        field (str | None): Field of the ticket to be monitored
218
        expected_value (str | None): Expected value of the field
219
        field_checker_func (Callable | None): Custom function to check field values
220
    """
221
    
222
    template_fields: Sequence[str] = ("ticket_id",)
223
    
224
    def __init__(
225
        self,
226
        *,
227
        jira_conn_id: str = 'jira_default',
228
        ticket_id: str | None = None,
229
        field: str | None = None,
230
        expected_value: str | None = None,
231
        field_checker_func: Callable | None = None,
232
        **kwargs,
233
    ) -> None: ...
234
    
235
    def poke(self, context: Context) -> Any:
236
        """
237
        Poke method to check specific Jira ticket field.
238
        
239
        Args:
240
            context: Airflow task context
241
            
242
        Returns:
243
            Any: Result from field checker or default issue field checker
244
        """
245
    
246
    def issue_field_checker(self, issue: Issue) -> bool | None:
247
        """
248
        Check issue using different conditions to prepare to evaluate sensor.
249
        
250
        Args:
251
            issue: Jira Issue object
252
            
253
        Returns:
254
            bool | None: True if field matches expected value, False/None otherwise
255
        """
256
```
257

258
## Deprecation Warnings
259

260
All modules in this package emit deprecation warnings when imported:
261

262
```python
263
warnings.warn(
264
    "This module is deprecated. Please use `airflow.providers.atlassian.jira.*`.",
265
    DeprecationWarning,
266
    stacklevel=2,
267
)
268
```
269

270
## Migration Guide
271

272
To migrate from this deprecated package:
273

274
1. **Update imports**:
275
   ```python
276
   # Old (deprecated)
277
   from airflow.providers.jira.hooks.jira import JiraHook
278
   from airflow.providers.jira.operators.jira import JiraOperator
279
   from airflow.providers.jira.sensors.jira import JiraSensor, JiraTicketSensor
280
   
281
   # New (recommended)
282
   from airflow.providers.atlassian.jira.hooks.jira import JiraHook
283
   from airflow.providers.atlassian.jira.operators.jira import JiraOperator
284
   from airflow.providers.atlassian.jira.sensors.jira import JiraSensor, JiraTicketSensor
285
   ```
286

287
2. **Update package dependencies**:
288
   ```bash
289
   # Remove deprecated package
290
   pip uninstall apache-airflow-providers-jira
291
   
292
   # Install replacement package
293
   pip install apache-airflow-providers-atlassian-jira
294
   ```
295

296
3. **Update connection configurations**: No changes needed - the same connection IDs and configurations work with the new package.
297

298
## Types
299

300
```python { .api }
301
# Re-exported types from underlying dependencies
302
from typing import Any, Callable, Sequence
303
from jira import JIRA
304
from jira.resources import Issue
305
from airflow.hooks.base import BaseHook
306
from airflow.models import BaseOperator
307
from airflow.sensors.base import BaseSensorOperator
308
from airflow.utils.context import Context
309
from airflow.exceptions import AirflowException
310
from jira.exceptions import JIRAError
311
```
312

313
## Error Handling
314

315
Since this package only re-exports classes, error handling is delegated to the underlying `apache-airflow-providers-atlassian-jira` package. Common exceptions include:
316

317
- `JIRAError`: Raised when JIRA API operations fail
318
- `AirflowException`: Raised when Airflow-specific operations fail
319

320
Refer to the replacement package's documentation for specific error handling patterns and exception types.