0
# Apache Airflow Providers Zendesk
1

2
Apache Airflow provider package for integrating with Zendesk customer service platform. This provider enables Airflow DAGs to interact with Zendesk's API through a standardized hook interface, allowing automated customer service workflows and data synchronization.
3

4
## Package Information
5

6
- **Package Name**: apache-airflow-providers-zendesk
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install apache-airflow-providers-zendesk`
10
- **Requirements**: Apache Airflow >= 2.10.0, zenpy >= 2.0.40
11
- **Python Versions**: 3.10, 3.11, 3.12, 3.13
12

13
## Core Imports
14

15
```python
16
from airflow.providers.zendesk.hooks.zendesk import ZendeskHook
17
```
18

19
Version compatibility imports:
20

21
```python
22
from airflow.providers.zendesk.version_compat import BaseHook, BaseOperator
23
```
24

25
Provider info:
26

27
```python  
28
from airflow.providers.zendesk.get_provider_info import get_provider_info
29
```
30

31
## Basic Usage
32

33
```python
34
from airflow.providers.zendesk.hooks.zendesk import ZendeskHook
35
from airflow import DAG
36
from airflow.decorators import task
37
from datetime import datetime
38

39
@task
40
def manage_zendesk_tickets():
41
    # Initialize hook with connection ID
42
    hook = ZendeskHook(zendesk_conn_id='zendesk_default')
43
    
44
    # Search for tickets
45
    tickets = list(hook.search_tickets(status='open', type='incident'))
46
    
47
    # Get specific ticket
48
    if tickets:
49
        ticket = hook.get_ticket(tickets[0].id)
50
        print(f"Ticket {ticket.id}: {ticket.subject}")
51
    
52
    return len(tickets)
53

54
# DAG definition
55
with DAG(
56
    'zendesk_workflow',
57
    start_date=datetime(2023, 1, 1),
58
    schedule_interval=None,
59
    catchup=False
60
) as dag:
61
    manage_zendesk_tickets()
62
```
63

64
## Connection Configuration
65

66
Configure Zendesk connection in Airflow:
67

68
- **Connection Type**: `zendesk`
69
- **Host**: Your Zendesk domain (e.g., `yourcompany.zendesk.com`)
70
- **Login**: Zendesk email address
71
- **Password**: Zendesk password or API token
72

73
## Capabilities
74

75
### Zendesk Hook
76

77
Main hook class for interacting with Zendesk API through the zenpy client library.
78

79
```python { .api }
80
class ZendeskHook(BaseHook):
81
    """
82
    Interact with Zendesk. This hook uses the Zendesk conn_id.
83
    
84
    :param zendesk_conn_id: The Airflow connection used for Zendesk credentials.
85
    """
86
    
87
    conn_name_attr: str = "zendesk_conn_id"
88
    default_conn_name: str = "zendesk_default" 
89
    conn_type: str = "zendesk"
90
    hook_name: str = "Zendesk"
91
    
92
    def __init__(self, zendesk_conn_id: str = default_conn_name) -> None:
93
        """Initialize ZendeskHook with connection ID."""
94
    
95
    @classmethod
96
    def get_ui_field_behaviour(cls) -> dict[str, Any]:
97
        """
98
        Return UI field configuration for Airflow connection form.
99
        
100
        Returns:
101
            dict: Configuration hiding schema, port, extra fields and relabeling host/login
102
        """
103
    
104
    def get_conn(self) -> Zenpy:
105
        """
106
        Get the underlying Zenpy client.
107
        
108
        Returns:
109
            zenpy.Zenpy: Configured Zenpy client instance
110
        """
111
    
112
    def get_ticket(self, ticket_id: int) -> Ticket:
113
        """
114
        Retrieve ticket by ID.
115
        
116
        Args:
117
            ticket_id: The ID of the ticket to retrieve
118
            
119
        Returns:
120
            Ticket: Zendesk ticket object
121
        """
122
    
123
    def search_tickets(self, **kwargs) -> SearchResultGenerator:
124
        """
125
        Search tickets with optional parameters.
126
        
127
        Args:
128
            **kwargs: Search fields for zenpy search method (status, type, priority, etc.)
129
            
130
        Returns:
131
            SearchResultGenerator: Generator of matching Ticket objects
132
        """
133
    
134
    def create_tickets(self, tickets: Ticket | list[Ticket], **kwargs) -> TicketAudit | JobStatus:
135
        """
136
        Create single ticket or multiple tickets.
137
        
138
        Args:
139
            tickets: Single Ticket or list of Ticket objects to create
140
            **kwargs: Additional fields for zenpy create method
141
            
142
        Returns:
143
            TicketAudit: Information about ticket created (single ticket)
144
            JobStatus: Job status object (bulk request)
145
        """
146
    
147
    def update_tickets(self, tickets: Ticket | list[Ticket], **kwargs) -> TicketAudit | JobStatus:
148
        """
149
        Update single ticket or multiple tickets.
150
        
151
        Args:
152
            tickets: Updated Ticket or list of Ticket objects
153
            **kwargs: Additional fields for zenpy update method
154
            
155
        Returns:
156
            TicketAudit: Information about ticket updated (single ticket)
157
            JobStatus: Job status object (bulk request)
158
        """
159
    
160
    def delete_tickets(self, tickets: Ticket | list[Ticket], **kwargs) -> None:
161
        """
162
        Delete single ticket or multiple tickets.
163
        
164
        Args:
165
            tickets: Ticket or list of Ticket objects to delete
166
            **kwargs: Additional fields for zenpy delete method
167
            
168
        Returns:
169
            None: Returns nothing on success, raises APIException on failure
170
        """
171
    
172
    def get(self, *args, **kwargs):
173
        """
174
        Make custom GET request using zenpy client's users API.
175
        
176
        Note: This is an alias to the underlying zenpy client's users._get method.
177
        
178
        Args:
179
            *args: Positional arguments passed to zenpy client
180
            **kwargs: Keyword arguments passed to zenpy client
181
            
182
        Returns:
183
            API response from zenpy client
184
        """
185
```
186

187
### Version Compatibility Utilities
188

189
Compatibility functions and constants for different Airflow versions.
190

191
```python { .api }
192
def get_base_airflow_version_tuple() -> tuple[int, int, int]:
193
    """
194
    Get Airflow version as tuple.
195
    
196
    Returns:
197
        tuple[int, int, int]: Major, minor, micro version numbers
198
    """
199

200
# Version check constants  
201
AIRFLOW_V_3_0_PLUS: bool  # Whether running Airflow 3.0+
202
AIRFLOW_V_3_1_PLUS: bool  # Whether running Airflow 3.1+
203

204
# Version-dependent imports
205
BaseHook: type  # From airflow.sdk or airflow.hooks.base
206
BaseOperator: type  # From airflow.sdk or airflow.models
207
```
208

209
**Import from version_compat module:**
210

211
```python
212
from airflow.providers.zendesk.version_compat import (
213
    get_base_airflow_version_tuple,
214
    AIRFLOW_V_3_0_PLUS,
215
    AIRFLOW_V_3_1_PLUS,
216
    BaseHook,
217
    BaseOperator
218
)
219
```
220

221
### Provider Information
222

223
Function to retrieve provider metadata for Airflow discovery.
224

225
```python { .api }
226
def get_provider_info() -> dict:
227
    """
228
    Get provider package information.
229
    
230
    Returns:
231
        dict: Provider metadata including package name, integrations, hooks, and connection types
232
    """
233
```
234

235
## Types
236

237
Types from the zenpy library that are commonly used with this provider:
238

239
```python { .api }
240
# From zenpy library
241
class Zenpy:
242
    """Main zenpy client for Zendesk API."""
243

244
class Ticket:
245
    """Zendesk ticket object containing ticket data and methods."""
246
    
247
    id: int
248
    subject: str
249
    description: str
250
    status: str
251
    priority: str
252
    # ... additional ticket fields
253

254
class TicketAudit:
255
    """Information about ticket creation/update operations."""
256

257
class JobStatus:
258
    """Status information for bulk operations."""
259

260
class SearchResultGenerator:
261
    """Generator yielding search results from Zendesk API."""
262

263
# Union types for method parameters
264
TicketInput = Ticket | list[Ticket]
265
TicketResult = TicketAudit | JobStatus
266
```
267

268
## Usage Examples
269

270
### Create and Update Tickets
271

272
```python
273
from airflow.providers.zendesk.hooks.zendesk import ZendeskHook
274
from zenpy.lib.api_objects import Ticket
275

276
hook = ZendeskHook()
277

278
# Create a new ticket
279
new_ticket = Ticket(
280
    subject="Integration Test Ticket",
281
    description="This is a test ticket created via Airflow",
282
    priority="normal"
283
)
284

285
audit = hook.create_tickets(new_ticket)
286
print(f"Created ticket ID: {audit.ticket.id}")
287

288
# Update the ticket
289
new_ticket.status = "solved"
290
update_audit = hook.update_tickets(new_ticket)
291
print(f"Updated ticket status: {update_audit.ticket.status}")
292
```
293

294
### Bulk Operations
295

296
```python
297
# Create multiple tickets
298
tickets = [
299
    Ticket(subject=f"Batch Ticket {i}", description=f"Description {i}")
300
    for i in range(1, 4)
301
]
302

303
job_status = hook.create_tickets(tickets)
304
print(f"Bulk create job ID: {job_status.id}")
305

306
# Search and filter tickets
307
open_tickets = list(hook.search_tickets(status="open", type="incident"))
308
print(f"Found {len(open_tickets)} open incident tickets")
309
```
310

311
### Custom API Access
312

313
```python
314
# Access underlying zenpy client for advanced operations
315
zenpy_client = hook.get_conn()
316

317
# Use zenpy client directly
318
users = zenpy_client.users.me()
319
print(f"Current user: {users.name}")
320

321
# Note: The get method is an alias to zenpy client's users._get method
322
# For other API endpoints, use the zenpy client directly
323
response = zenpy_client.organizations()
324
organizations = [org.to_dict() for org in response]
325
```
326

327
## Error Handling
328

329
The provider uses zenpy's exception handling. Common exceptions include:
330

331
- **APIException**: Raised when API operations fail
332
- **Connection errors**: Raised when unable to connect to Zendesk
333
- **Authentication errors**: Raised when credentials are invalid
334

335
```python
336
from zenpy.lib.exception import APIException
337

338
try:
339
    ticket = hook.get_ticket(999999)  # Non-existent ticket
340
except APIException as e:
341
    print(f"API Error: {e}")
342
```