0
# Custom Components
1
2
Python components for specialized data extraction and transformation of Zendesk Chat API responses.
3
4
## Capabilities
5
6
### Record Extraction
7
8
Custom record extractors for processing complex API response structures that require specialized handling.
9
10
```python { .api }
11
class ZendeskChatBansRecordExtractor(RecordExtractor):
12
"""
13
Custom extractor for processing bans data by unnesting visitor and ip_address fields.
14
15
Processes the /bans endpoint response which contains nested structures for
16
different ban types (visitor bans and IP address bans) and flattens them
17
into individual records sorted by creation date.
18
"""
19
20
def extract_records(
21
self,
22
response: requests.Response
23
) -> Iterable[Mapping[str, Any]]:
24
"""
25
Extract and process ban records from API response.
26
27
Args:
28
response: HTTP response from Zendesk Chat bans API endpoint
29
30
Returns:
31
Iterator of processed ban records, sorted by created_at timestamp
32
33
Processing:
34
1. Extracts ip_address and visitor ban arrays from response
35
2. Combines both arrays into single list of ban records
36
3. Sorts records by created_at timestamp (handles None values)
37
4. Yields individual ban records for stream processing
38
"""
39
```
40
41
### Base Record Extractor
42
43
Base class functionality inherited by custom extractors.
44
45
```python { .api }
46
class RecordExtractor:
47
"""
48
Base class for extracting records from API responses.
49
50
All custom extractors inherit from this class and implement
51
the extract_records method to define custom processing logic.
52
"""
53
54
def extract_records(
55
self,
56
response: requests.Response
57
) -> Iterable[Mapping[str, Any]]:
58
"""
59
Abstract method for extracting records from HTTP response.
60
61
Args:
62
response: HTTP response from API endpoint
63
64
Returns:
65
Iterator of extracted records
66
"""
67
```
68
69
### DateTime Processing
70
71
Utility for parsing and handling datetime strings in API responses.
72
73
```python { .api }
74
date_time_parser: DatetimeParser
75
"""
76
Global datetime parser instance for processing timestamp fields.
77
78
Used by custom extractors to parse created_at and other timestamp
79
fields with consistent formatting and timezone handling.
80
"""
81
82
class DatetimeParser:
83
"""
84
Utility class for parsing datetime strings from API responses.
85
86
Handles various datetime formats and provides timezone-aware
87
parsing for timestamp fields in Zendesk Chat API data.
88
"""
89
90
_UNIX_EPOCH: str = "1970-01-01T00:00:00Z"
91
"""Default timestamp for records with missing created_at values"""
92
93
def parse(
94
self,
95
date: str,
96
format: str = "%Y-%m-%dT%H:%M:%SZ"
97
) -> datetime:
98
"""
99
Parse datetime string using specified format.
100
101
Args:
102
date: Datetime string to parse
103
format: Format string for parsing (default ISO format)
104
105
Returns:
106
Parsed datetime object
107
"""
108
```
109
110
### Component Integration
111
112
Custom components are integrated with the declarative manifest through the CustomRecordExtractor configuration.
113
114
```yaml { .api }
115
# From manifest.yaml - bans stream configuration
116
record_selector:
117
type: RecordSelector
118
extractor:
119
type: CustomRecordExtractor
120
class_name: source_declarative_manifest.components.ZendeskChatBansRecordExtractor
121
122
# Components are loaded by the declarative manifest framework
123
# using the fully qualified class name in the manifest configuration
124
```
125
126
### Usage Examples
127
128
```python
129
import requests
130
from components import ZendeskChatBansRecordExtractor
131
132
# Create extractor instance
133
extractor = ZendeskChatBansRecordExtractor()
134
135
# Mock API response with nested ban data
136
response_data = {
137
"ip_address": [
138
{
139
"reason": "spam",
140
"type": "ip_address",
141
"id": 1234,
142
"created_at": "2021-04-21T14:42:46Z",
143
"ip_address": "192.168.1.100"
144
}
145
],
146
"visitor": [
147
{
148
"type": "visitor",
149
"id": 4444,
150
"visitor_name": "Visitor 4444",
151
"visitor_id": "visitor_id_123",
152
"reason": "inappropriate_behavior",
153
"created_at": "2021-04-27T13:25:01Z"
154
}
155
]
156
}
157
158
# Create mock response
159
response = requests.Response()
160
response._content = json.dumps(response_data).encode()
161
162
# Extract records
163
records = list(extractor.extract_records(response))
164
165
# Records are now flattened and sorted by creation date:
166
# [
167
# {"reason": "spam", "type": "ip_address", "id": 1234, ...},
168
# {"type": "visitor", "id": 4444, "visitor_name": "Visitor 4444", ...}
169
# ]
170
```
171
172
## Types
173
174
```python { .api }
175
# Core types
176
Record = Dict[str, Any]
177
"""Individual record extracted from API response"""
178
179
RecordIterator = Iterable[Mapping[str, Any]]
180
"""Iterator of extracted records"""
181
182
ResponseData = Dict[str, Any]
183
"""Parsed JSON data from API response"""
184
185
# Ban record types
186
BanRecord = Dict[str, Union[str, int]]
187
"""Individual ban record (visitor or IP address ban)"""
188
189
IPAddressBan = Dict[str, Union[str, int]]
190
"""IP address ban record with ip_address field"""
191
192
VisitorBan = Dict[str, Union[str, int]]
193
"""Visitor ban record with visitor_name and visitor_id fields"""
194
195
BansList = List[BanRecord]
196
"""List of processed ban records"""
197
198
# Datetime types
199
DatetimeString = str
200
"""ISO format datetime string (YYYY-MM-DDTHH:MM:SSZ)"""
201
202
DatetimeFormat = str
203
"""Format string for datetime parsing"""
204
```