tallyfy 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of tallyfy might be problematic. Click here for more details.
- tallyfy/core.py +5 -1
- tallyfy/models.py +1 -1
- {tallyfy-1.0.2.dist-info → tallyfy-1.0.4.dist-info}/METADATA +2 -2
- {tallyfy-1.0.2.dist-info → tallyfy-1.0.4.dist-info}/RECORD +7 -8
- tallyfy/README.md +0 -634
- {tallyfy-1.0.2.dist-info → tallyfy-1.0.4.dist-info}/WHEEL +0 -0
- {tallyfy-1.0.2.dist-info → tallyfy-1.0.4.dist-info}/licenses/LICENSE +0 -0
- {tallyfy-1.0.2.dist-info → tallyfy-1.0.4.dist-info}/top_level.txt +0 -0
tallyfy/core.py
CHANGED
|
@@ -219,7 +219,11 @@ class TallyfySDK(BaseSDK):
|
|
|
219
219
|
def get_template(self, org_id: str, template_id: Optional[str] = None, template_name: Optional[str] = None):
|
|
220
220
|
"""Get template by ID or name."""
|
|
221
221
|
return self.templates.get_template(org_id, template_id, template_name)
|
|
222
|
-
|
|
222
|
+
|
|
223
|
+
def get_all_templates(self, org_id: str):
|
|
224
|
+
"""Get all templates by organization."""
|
|
225
|
+
return self.templates.get_all_templates(org_id)
|
|
226
|
+
|
|
223
227
|
def update_template_metadata(self, org_id: str, template_id: str, **kwargs):
|
|
224
228
|
"""Update template metadata."""
|
|
225
229
|
return self.templates.update_template_metadata(org_id, template_id, **kwargs)
|
tallyfy/models.py
CHANGED
|
@@ -1062,7 +1062,7 @@ class TemplatesList:
|
|
|
1062
1062
|
|
|
1063
1063
|
@classmethod
|
|
1064
1064
|
def from_dict(cls, data: Dict[str, Any]) -> 'TemplatesList':
|
|
1065
|
-
"""Create
|
|
1065
|
+
"""Create TemplatesList instance from dictionary"""
|
|
1066
1066
|
templates_data = data.get('data', [])
|
|
1067
1067
|
templates = [Template.from_dict(template_data) for template_data in templates_data]
|
|
1068
1068
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tallyfy
|
|
3
|
-
Version: 1.0.
|
|
3
|
+
Version: 1.0.4
|
|
4
4
|
Summary: A comprehensive Python SDK for interacting with the Tallyfy API
|
|
5
5
|
Home-page: https://github.com/tallyfy/tallyfy-sdk
|
|
6
6
|
Author: Tallyfy
|
|
@@ -674,5 +674,5 @@ For bugs, feature requests, or questions:
|
|
|
674
674
|
2. Contact us at: support@tallyfy.com
|
|
675
675
|
---
|
|
676
676
|
|
|
677
|
-
**Version:** 1.0.
|
|
677
|
+
**Version:** 1.0.4
|
|
678
678
|
**Last Updated:** 2025
|
|
@@ -1,14 +1,13 @@
|
|
|
1
1
|
tallyfy/BUILD.md,sha256=38Ley-pN-MPfFAsLT98fV0Sz05JHMmcenXyy7P17tZ0,85
|
|
2
|
-
tallyfy/README.md,sha256=aBmihbXYIgWGUUpSeJzR2FSJWpDK3qMBAdTl8aMbveg,21368
|
|
3
2
|
tallyfy/__init__.py,sha256=E4eHCzUwVOD9r3PQBXHdJv0KYPSNe-2lH7h1yKdUHQ8,492
|
|
4
|
-
tallyfy/core.py,sha256=
|
|
3
|
+
tallyfy/core.py,sha256=crdfYp8jzB-MFLkUsfelNBzm9DfOyFCnK0neQEhzD4w,16464
|
|
5
4
|
tallyfy/form_fields_management.py,sha256=-ifTFKQuA3pcftKfPAyNCV840DOJPqRvJPsBCDNXbWU,24223
|
|
6
|
-
tallyfy/models.py,sha256=
|
|
5
|
+
tallyfy/models.py,sha256=Pmcl3B_zTURnA--E72hpuRi4DHpl6FdWQM84OfPeGqo,38070
|
|
7
6
|
tallyfy/task_management.py,sha256=DIfhbo8qU3DWzuLKBZtwPlFta_D6Ip9HH3PUltr3T2o,14785
|
|
8
7
|
tallyfy/template_management.py,sha256=peYgh4vkhKT5L_782pPzCpJzE18tFQNnIWQ72lyiovU,121138
|
|
9
8
|
tallyfy/user_management.py,sha256=R7L8Nsszm7htvZDRou7C0zQvgFx0pbNmcjHHyWYbl3g,8581
|
|
10
|
-
tallyfy-1.0.
|
|
11
|
-
tallyfy-1.0.
|
|
12
|
-
tallyfy-1.0.
|
|
13
|
-
tallyfy-1.0.
|
|
14
|
-
tallyfy-1.0.
|
|
9
|
+
tallyfy-1.0.4.dist-info/licenses/LICENSE,sha256=8HUsrXnc3l2sZxhPV9Z1gYinq76Q2Ym7ahYJy57QlLc,1063
|
|
10
|
+
tallyfy-1.0.4.dist-info/METADATA,sha256=moIhI0vL6Up4mj06ORZzuYp-kPGuipVtrceMBLMPdVM,23252
|
|
11
|
+
tallyfy-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
|
12
|
+
tallyfy-1.0.4.dist-info/top_level.txt,sha256=yIycWbR61EZJD0MYRPwUQjOS2XZw5B5jCWx1IP73KcM,8
|
|
13
|
+
tallyfy-1.0.4.dist-info/RECORD,,
|
tallyfy/README.md
DELETED
|
@@ -1,634 +0,0 @@
|
|
|
1
|
-
# Tallyfy SDK
|
|
2
|
-
|
|
3
|
-
A comprehensive Python SDK for interacting with the Tallyfy API. This SDK provides a clean, modular interface for managing users, tasks, templates, and form fields in your Tallyfy organization.
|
|
4
|
-
|
|
5
|
-
## Table of Contents
|
|
6
|
-
|
|
7
|
-
- [Installation](#installation)
|
|
8
|
-
- [Quick Start](#quick-start)
|
|
9
|
-
- [Architecture](#architecture)
|
|
10
|
-
- [Core Features](#core-features)
|
|
11
|
-
- [API Reference](#api-reference)
|
|
12
|
-
- [Data Models](#data-models)
|
|
13
|
-
- [Error Handling](#error-handling)
|
|
14
|
-
- [Examples](#examples)
|
|
15
|
-
- [Advanced Usage](#advanced-usage)
|
|
16
|
-
- [Contributing](#contributing)
|
|
17
|
-
|
|
18
|
-
## Installation
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
pip install -r requirements.txt
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
**Dependencies:**
|
|
25
|
-
- `requests` - HTTP client library
|
|
26
|
-
- `typing` - Type hints support (Python 3.5+)
|
|
27
|
-
|
|
28
|
-
## Quick Start
|
|
29
|
-
|
|
30
|
-
```python
|
|
31
|
-
from tallyfy import TallyfySDK
|
|
32
|
-
|
|
33
|
-
# Initialize the SDK
|
|
34
|
-
sdk = TallyfySDK(
|
|
35
|
-
api_key="your_api_key_here"
|
|
36
|
-
)
|
|
37
|
-
|
|
38
|
-
# Get organization users
|
|
39
|
-
users = sdk.users.get_organization_users(org_id="your_org_id")
|
|
40
|
-
|
|
41
|
-
# Get current user's tasks
|
|
42
|
-
my_tasks = sdk.tasks.get_my_tasks(org_id="your_org_id")
|
|
43
|
-
|
|
44
|
-
# Search for templates
|
|
45
|
-
templates = sdk.search(org_id="your_org_id", search_query="onboarding", search_type="blueprint")
|
|
46
|
-
|
|
47
|
-
# Get a specific template
|
|
48
|
-
template = sdk.templates.get_template(org_id="your_org_id", template_name="Employee Onboarding")
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
## Architecture
|
|
52
|
-
|
|
53
|
-
The Tallyfy SDK follows a modular architecture with specialized management classes and comprehensive data models:
|
|
54
|
-
|
|
55
|
-
### Core Components
|
|
56
|
-
|
|
57
|
-
- **`TallyfySDK`** - Main SDK class that orchestrates all operations with backward compatibility methods
|
|
58
|
-
- **`BaseSDK`** - Base class with HTTP request handling, retry logic, and connection pooling
|
|
59
|
-
- **Management Modules:**
|
|
60
|
-
- `UserManagement` - User and guest operations with full profile support
|
|
61
|
-
- `TaskManagement` - Task and process operations with natural language processing
|
|
62
|
-
- `TemplateManagement` - Template/checklist operations with automation analysis
|
|
63
|
-
- `FormFieldManagement` - Form field operations with AI-powered suggestions
|
|
64
|
-
- **Utility Modules:**
|
|
65
|
-
- `DateExtractor` - Natural language date parsing and task extraction
|
|
66
|
-
- `TallyfyError` - Custom exception handling with status codes and response data
|
|
67
|
-
|
|
68
|
-
### File Structure
|
|
69
|
-
|
|
70
|
-
```
|
|
71
|
-
tallyfy/
|
|
72
|
-
├── __init__.py # SDK exports and version
|
|
73
|
-
├── core.py # BaseSDK and TallyfySDK classes
|
|
74
|
-
├── models.py # Data models and types
|
|
75
|
-
├── user_management.py # User and guest management
|
|
76
|
-
├── task_management.py # Task and process management
|
|
77
|
-
├── template_management.py # Template management
|
|
78
|
-
├── form_fields_management.py # Form field management
|
|
79
|
-
└── README.md # This documentation
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
## Core Features
|
|
83
|
-
|
|
84
|
-
### 🔐 Authentication & Security
|
|
85
|
-
- Bearer token authentication with session management
|
|
86
|
-
- Configurable request timeouts and connection pooling
|
|
87
|
-
- Automatic retry logic for transient failures (5xx errors)
|
|
88
|
-
- No retry for client errors (4xx) to prevent API abuse
|
|
89
|
-
- Comprehensive error handling with detailed error information
|
|
90
|
-
|
|
91
|
-
### 👥 User Management
|
|
92
|
-
- Get organization members with full profile data (country, timezone, job details)
|
|
93
|
-
- Get minimal user lists for performance-critical operations
|
|
94
|
-
- Manage guests and external users with guest-specific features
|
|
95
|
-
- Invite new users to organization with role assignment
|
|
96
|
-
- Support for user groups and permissions
|
|
97
|
-
|
|
98
|
-
### ✅ Task Management
|
|
99
|
-
- Get tasks for specific users or processes with filtering
|
|
100
|
-
- Create standalone tasks with rich assignment options
|
|
101
|
-
- **Natural language task creation** with automatic date/time extraction
|
|
102
|
-
- Search processes by name with fuzzy matching
|
|
103
|
-
- Advanced filtering for organization runs (status, owners, tags, etc.)
|
|
104
|
-
- Universal search across processes, templates, and tasks
|
|
105
|
-
|
|
106
|
-
### 📋 Template Management
|
|
107
|
-
- Get templates with full metadata and step details
|
|
108
|
-
- Search templates by name with exact and fuzzy matching
|
|
109
|
-
- Update template properties and metadata
|
|
110
|
-
- Duplicate templates with permission copying options
|
|
111
|
-
- **Automation management** - Create, update, and analyze conditional rules
|
|
112
|
-
- **Step dependency analysis** - Understand step visibility conditions
|
|
113
|
-
- **AI-powered deadline suggestions** for individual steps
|
|
114
|
-
- **Template health assessment** - Comprehensive analysis of template quality
|
|
115
|
-
- **Automation consolidation** - Optimize and merge redundant rules
|
|
116
|
-
- Add assignees and edit step descriptions
|
|
117
|
-
- Kickoff field management for template launch forms
|
|
118
|
-
|
|
119
|
-
### 📝 Form Field Management
|
|
120
|
-
- Add form fields to template steps with comprehensive validation
|
|
121
|
-
- Support for text, dropdown, date, file upload, WYSIWYG editor fields
|
|
122
|
-
- Update field properties, validation rules, and positioning
|
|
123
|
-
- Move fields between steps with automatic reordering
|
|
124
|
-
- **AI-powered field suggestions** based on step analysis
|
|
125
|
-
- Manage dropdown options with bulk updates
|
|
126
|
-
- **Smart field recommendations** with confidence scoring
|
|
127
|
-
- Field dependency management and conditional logic
|
|
128
|
-
|
|
129
|
-
### 🔍 Search & Discovery
|
|
130
|
-
- Universal search across processes, templates, and tasks
|
|
131
|
-
- Exact and fuzzy matching with relevance scoring
|
|
132
|
-
- Pagination support with configurable page sizes
|
|
133
|
-
- Rich search results with metadata and context
|
|
134
|
-
- **Natural language date extraction** from search queries
|
|
135
|
-
- Process and template name-based search with suggestions
|
|
136
|
-
|
|
137
|
-
### 🤖 Natural Language Processing
|
|
138
|
-
- **Task creation from natural language** with automatic parsing
|
|
139
|
-
- **Date extraction** supporting various formats ("next Monday at 12PM", "tomorrow morning")
|
|
140
|
-
- **User/guest resolution** from names and emails
|
|
141
|
-
- **Smart task parsing** extracting titles, descriptions, and deadlines
|
|
142
|
-
- **Fuzzy matching** for user names and process titles
|
|
143
|
-
|
|
144
|
-
## API Reference
|
|
145
|
-
|
|
146
|
-
### SDK Initialization
|
|
147
|
-
|
|
148
|
-
```python
|
|
149
|
-
TallyfySDK(
|
|
150
|
-
api_key: str,
|
|
151
|
-
timeout: int = 30,
|
|
152
|
-
max_retries: int = 3,
|
|
153
|
-
retry_delay: float = 1.0
|
|
154
|
-
)
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
### User Management
|
|
158
|
-
|
|
159
|
-
```python
|
|
160
|
-
# Get all organization users
|
|
161
|
-
users = sdk.users.get_organization_users(org_id, with_groups=False)
|
|
162
|
-
|
|
163
|
-
# Get minimal user list
|
|
164
|
-
users_list = sdk.users.get_organization_users_list(org_id)
|
|
165
|
-
|
|
166
|
-
# Get organization guests
|
|
167
|
-
guests = sdk.users.get_organization_guests(org_id, with_stats=False)
|
|
168
|
-
|
|
169
|
-
# Invite user to organization
|
|
170
|
-
user = sdk.users.invite_user_to_organization(
|
|
171
|
-
org_id, email, first_name, last_name,
|
|
172
|
-
role="light", message=None
|
|
173
|
-
)
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
### Task Management
|
|
177
|
-
|
|
178
|
-
```python
|
|
179
|
-
# Get current user's tasks
|
|
180
|
-
my_tasks = sdk.tasks.get_my_tasks(org_id)
|
|
181
|
-
|
|
182
|
-
# Get specific user's tasks
|
|
183
|
-
user_tasks = sdk.tasks.get_user_tasks(org_id, user_id)
|
|
184
|
-
|
|
185
|
-
# Get tasks for a process
|
|
186
|
-
process_tasks = sdk.tasks.get_tasks_for_process(org_id, process_id=None, process_name="My Process")
|
|
187
|
-
|
|
188
|
-
# Get organization processes with filtering
|
|
189
|
-
runs = sdk.tasks.get_organization_runs(
|
|
190
|
-
org_id,
|
|
191
|
-
status="active",
|
|
192
|
-
owners="123,456",
|
|
193
|
-
checklist_id="template_id"
|
|
194
|
-
)
|
|
195
|
-
|
|
196
|
-
# Create standalone task
|
|
197
|
-
task = sdk.tasks.create_task(
|
|
198
|
-
org_id, title="Review Document",
|
|
199
|
-
deadline="2024-12-31T23:59:59Z",
|
|
200
|
-
description="Please review the attached document"
|
|
201
|
-
)
|
|
202
|
-
|
|
203
|
-
# Create task from natural language (via MCP Server)
|
|
204
|
-
task_result = create_task_from_text(
|
|
205
|
-
org_id,
|
|
206
|
-
"Create a task called Review Document with description Review the quarterly report the deadline is next Monday at 12PM",
|
|
207
|
-
user_emails=["john@company.com"],
|
|
208
|
-
max_assignable=2
|
|
209
|
-
)
|
|
210
|
-
|
|
211
|
-
# Search processes, templates, or tasks
|
|
212
|
-
results = sdk.tasks.search(org_id, "onboarding", search_type="process")
|
|
213
|
-
|
|
214
|
-
# Search for specific entity types
|
|
215
|
-
templates = sdk.tasks.search(org_id, "employee onboarding", search_type="blueprint")
|
|
216
|
-
tasks = sdk.tasks.search(org_id, "review", search_type="task")
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### Template Management
|
|
220
|
-
|
|
221
|
-
```python
|
|
222
|
-
# Get template by ID or name
|
|
223
|
-
template = sdk.templates.get_template(org_id, template_id=None, template_name="Onboarding")
|
|
224
|
-
|
|
225
|
-
# Get template with full step details
|
|
226
|
-
template_data = sdk.templates.get_template_with_steps(org_id, template_id)
|
|
227
|
-
|
|
228
|
-
# Update template metadata
|
|
229
|
-
updated = sdk.templates.update_template_metadata(
|
|
230
|
-
org_id, template_id,
|
|
231
|
-
title="New Title",
|
|
232
|
-
summary="Updated summary",
|
|
233
|
-
guidance="New guidance text"
|
|
234
|
-
)
|
|
235
|
-
|
|
236
|
-
# Get template steps
|
|
237
|
-
steps = sdk.templates.get_template_steps(org_id, template_id)
|
|
238
|
-
|
|
239
|
-
# Analyze step dependencies
|
|
240
|
-
dependencies = sdk.templates.get_step_dependencies(org_id, template_id, step_id)
|
|
241
|
-
|
|
242
|
-
# Get deadline suggestions
|
|
243
|
-
deadline_suggestion = sdk.templates.suggest_step_deadline(org_id, template_id, step_id)
|
|
244
|
-
|
|
245
|
-
# Advanced template operations
|
|
246
|
-
duplicated = sdk.templates.duplicate_template(org_id, template_id, "New Template Name", copy_permissions=True)
|
|
247
|
-
|
|
248
|
-
# Automation management
|
|
249
|
-
automation_data = {
|
|
250
|
-
"automated_alias": "Auto-assign reviewer",
|
|
251
|
-
"conditions": [{"field_id": "department", "operator": "equals", "value": "Engineering"}],
|
|
252
|
-
"actions": [{"type": "assign_step", "step_id": "review_step", "assignee_type": "user", "assignee_id": "123"}]
|
|
253
|
-
}
|
|
254
|
-
automation = sdk.templates.create_automation_rule(org_id, template_id, automation_data)
|
|
255
|
-
|
|
256
|
-
# Analyze automation conflicts and redundancies
|
|
257
|
-
analysis = sdk.templates.analyze_template_automations(org_id, template_id)
|
|
258
|
-
|
|
259
|
-
# Get consolidation suggestions
|
|
260
|
-
suggestions = sdk.templates.suggest_automation_consolidation(org_id, template_id)
|
|
261
|
-
|
|
262
|
-
# Assess overall template health
|
|
263
|
-
health_report = sdk.templates.assess_template_health(org_id, template_id)
|
|
264
|
-
|
|
265
|
-
# Add kickoff fields
|
|
266
|
-
kickoff_data = {
|
|
267
|
-
"field_type": "text",
|
|
268
|
-
"label": "Project Name",
|
|
269
|
-
"required": True,
|
|
270
|
-
"validation_rules": {"min_length": 3}
|
|
271
|
-
}
|
|
272
|
-
kickoff_field = sdk.templates.add_kickoff_field(org_id, template_id, kickoff_data)
|
|
273
|
-
|
|
274
|
-
# Add assignees to step
|
|
275
|
-
assignees = {"users": [123, 456], "groups": ["managers"], "guests": ["contractor@company.com"]}
|
|
276
|
-
sdk.templates.add_assignees_to_step(org_id, template_id, step_id, assignees)
|
|
277
|
-
|
|
278
|
-
# Edit step description
|
|
279
|
-
sdk.templates.edit_description_on_step(org_id, template_id, step_id, "Updated step description with detailed instructions")
|
|
280
|
-
|
|
281
|
-
# Add new step to template
|
|
282
|
-
step_data = {
|
|
283
|
-
"title": "Quality Review",
|
|
284
|
-
"description": "Perform final quality check",
|
|
285
|
-
"position": 5,
|
|
286
|
-
"assignees": {"users": [789]}
|
|
287
|
-
}
|
|
288
|
-
new_step = sdk.templates.add_step_to_template(org_id, template_id, step_data)
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
### Form Field Management
|
|
292
|
-
|
|
293
|
-
```python
|
|
294
|
-
# Add form field to step
|
|
295
|
-
field_data = {
|
|
296
|
-
"field_type": "text",
|
|
297
|
-
"label": "Customer Name",
|
|
298
|
-
"required": True,
|
|
299
|
-
"position": 1
|
|
300
|
-
}
|
|
301
|
-
field = sdk.form_fields.add_form_field_to_step(org_id, template_id, step_id, field_data)
|
|
302
|
-
|
|
303
|
-
# Update form field
|
|
304
|
-
updated_field = sdk.form_fields.update_form_field(
|
|
305
|
-
org_id, template_id, step_id, field_id,
|
|
306
|
-
label="Updated Label",
|
|
307
|
-
required=False
|
|
308
|
-
)
|
|
309
|
-
|
|
310
|
-
# Move field between steps
|
|
311
|
-
success = sdk.form_fields.move_form_field(
|
|
312
|
-
org_id, template_id, from_step, field_id, to_step, position=2
|
|
313
|
-
)
|
|
314
|
-
|
|
315
|
-
# Delete form field
|
|
316
|
-
success = sdk.form_fields.delete_form_field(org_id, template_id, step_id, field_id)
|
|
317
|
-
|
|
318
|
-
# Get dropdown options
|
|
319
|
-
options = sdk.form_fields.get_dropdown_options(org_id, template_id, step_id, field_id)
|
|
320
|
-
|
|
321
|
-
# Update dropdown options
|
|
322
|
-
success = sdk.form_fields.update_dropdown_options(
|
|
323
|
-
org_id, template_id, step_id, field_id,
|
|
324
|
-
["Option 1", "Option 2", "Option 3"]
|
|
325
|
-
)
|
|
326
|
-
|
|
327
|
-
# Get AI-powered field suggestions
|
|
328
|
-
suggestions = sdk.form_fields.suggest_form_fields_for_step(org_id, template_id, step_id)
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
## Data Models
|
|
332
|
-
|
|
333
|
-
The SDK provides comprehensive dataclasses for type safety and easy data access:
|
|
334
|
-
|
|
335
|
-
### Core Models
|
|
336
|
-
|
|
337
|
-
- **`User`** - Organization member with full profile data (country, timezone, job details)
|
|
338
|
-
- **`Guest`** - External user with limited access and guest-specific details
|
|
339
|
-
- **`GuestDetails`** - Extended guest information and statistics
|
|
340
|
-
- **`Task`** - Individual work item with owners, deadlines, and process linkage
|
|
341
|
-
- **`Run`** - Process instance (workflow execution) with progress tracking
|
|
342
|
-
- **`Template`** - Complete template/checklist definition with automation rules
|
|
343
|
-
- **`Step`** - Individual step within a template with conditions and assignments
|
|
344
|
-
|
|
345
|
-
### Assignment and Ownership Models
|
|
346
|
-
|
|
347
|
-
- **`TaskOwners`** - Task assignment information supporting users, guests, and groups
|
|
348
|
-
- **`RunProgress`** - Process completion tracking with step-level progress
|
|
349
|
-
- **`Country`** - Geographic data for user profiles
|
|
350
|
-
- **`Folder`** - Organizational folder structure for templates and processes
|
|
351
|
-
|
|
352
|
-
### Template and Automation Models
|
|
353
|
-
|
|
354
|
-
- **`Tag`** - Industry and topic classification tags
|
|
355
|
-
- **`PrerunField`** - Form fields for template kickoff with validation rules
|
|
356
|
-
- **`AutomationCondition`** - Conditional logic for workflow automation
|
|
357
|
-
- **`AutomationAction`** - Actions triggered by automation rules
|
|
358
|
-
- **`AutomatedAction`** - Complete automation rule with conditions and actions
|
|
359
|
-
- **`AutomationDeadline`** - Deadline configuration for automated actions
|
|
360
|
-
- **`AutomationAssignees`** - Assignee configuration for automated actions
|
|
361
|
-
|
|
362
|
-
### Step and Form Models
|
|
363
|
-
|
|
364
|
-
- **`Capture`** - Form fields within steps with validation and positioning
|
|
365
|
-
- **`StepStartDate`** - Start date configuration for steps
|
|
366
|
-
- **`StepDeadline`** - Deadline configuration for individual steps
|
|
367
|
-
- **`StepBpToLaunch`** - Sub-process launch configuration
|
|
368
|
-
|
|
369
|
-
### Search and Utility Models
|
|
370
|
-
|
|
371
|
-
- **`SearchResult`** - Unified search results for templates, processes, and tasks
|
|
372
|
-
- **`TallyfyError`** - Custom exception with status codes and response data
|
|
373
|
-
|
|
374
|
-
### Model Features
|
|
375
|
-
|
|
376
|
-
- **Automatic parsing** from API responses via `from_dict()` class methods
|
|
377
|
-
- **Type safety** with comprehensive type hints
|
|
378
|
-
- **Nested object support** for complex data structures
|
|
379
|
-
- **Default value handling** for optional fields
|
|
380
|
-
|
|
381
|
-
Example model usage:
|
|
382
|
-
|
|
383
|
-
```python
|
|
384
|
-
# Models automatically parse API responses
|
|
385
|
-
users = sdk.users.get_organization_users(org_id)
|
|
386
|
-
for user in users:
|
|
387
|
-
print(f"{user.full_name} ({user.email})")
|
|
388
|
-
if user.country:
|
|
389
|
-
print(f"Country: {user.country.name}")
|
|
390
|
-
|
|
391
|
-
# Access nested data safely
|
|
392
|
-
template = sdk.templates.get_template(org_id, template_name="Onboarding")
|
|
393
|
-
if template.automated_actions:
|
|
394
|
-
for automation in template.automated_actions:
|
|
395
|
-
print(f"Automation: {automation.automated_alias}")
|
|
396
|
-
for condition in automation.conditions:
|
|
397
|
-
print(f" Condition: {condition.statement}")
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
## Error Handling
|
|
401
|
-
|
|
402
|
-
The SDK provides comprehensive error handling through the `TallyfyError` class:
|
|
403
|
-
|
|
404
|
-
```python
|
|
405
|
-
from tallyfy import TallyfyError
|
|
406
|
-
|
|
407
|
-
try:
|
|
408
|
-
users = sdk.users.get_organization_users("invalid_org_id")
|
|
409
|
-
except TallyfyError as e:
|
|
410
|
-
print(f"API Error: {e}")
|
|
411
|
-
print(f"Status Code: {e.status_code}")
|
|
412
|
-
print(f"Response Data: {e.response_data}")
|
|
413
|
-
except ValueError as e:
|
|
414
|
-
print(f"Validation Error: {e}")
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
### Error Types
|
|
418
|
-
|
|
419
|
-
- **`TallyfyError`** - API-specific errors with status codes and response data
|
|
420
|
-
- **`ValueError`** - Input validation errors for required parameters
|
|
421
|
-
- **`RequestException`** - Network and connection errors (automatically retried)
|
|
422
|
-
|
|
423
|
-
### Retry Logic
|
|
424
|
-
|
|
425
|
-
The SDK automatically retries failed requests with configurable settings:
|
|
426
|
-
|
|
427
|
-
- **Server errors (5xx)** - Automatically retried up to `max_retries` times
|
|
428
|
-
- **Client errors (4xx)** - Not retried (indicates user/input error)
|
|
429
|
-
- **Network errors** - Retried with exponential backoff
|
|
430
|
-
- **Timeout errors** - Retried with configurable delay
|
|
431
|
-
|
|
432
|
-
## Examples
|
|
433
|
-
|
|
434
|
-
### Complete User Onboarding Workflow
|
|
435
|
-
|
|
436
|
-
```python
|
|
437
|
-
from tallyfy import TallyfySDK, TaskOwners
|
|
438
|
-
|
|
439
|
-
sdk = TallyfySDK(api_key="your_api_key")
|
|
440
|
-
org_id = "your_org_id"
|
|
441
|
-
|
|
442
|
-
# 1. Invite new user
|
|
443
|
-
new_user = sdk.users.invite_user_to_organization(
|
|
444
|
-
org_id,
|
|
445
|
-
email="new.hire@company.com",
|
|
446
|
-
first_name="John",
|
|
447
|
-
last_name="Doe",
|
|
448
|
-
role="standard",
|
|
449
|
-
message="Welcome to the team! Please complete your onboarding."
|
|
450
|
-
)
|
|
451
|
-
|
|
452
|
-
# 2. Create onboarding task
|
|
453
|
-
if new_user:
|
|
454
|
-
owners = TaskOwners(users=[new_user.id])
|
|
455
|
-
onboarding_task = sdk.tasks.create_task(
|
|
456
|
-
org_id,
|
|
457
|
-
title="Complete Employee Onboarding",
|
|
458
|
-
deadline="2025-12-31 17:00:00",
|
|
459
|
-
description="Please complete all onboarding steps including HR paperwork and IT setup.",
|
|
460
|
-
owners=owners
|
|
461
|
-
)
|
|
462
|
-
print(f"Created onboarding task: {onboarding_task.id}")
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
### Template Analysis and Enhancement
|
|
466
|
-
|
|
467
|
-
```python
|
|
468
|
-
# Get template with full details
|
|
469
|
-
template_data = sdk.templates.get_template_with_steps(org_id, template_name="Project Kickoff")
|
|
470
|
-
|
|
471
|
-
if template_data:
|
|
472
|
-
template = template_data['template']
|
|
473
|
-
print(f"Template: {template.title}")
|
|
474
|
-
print(f"Steps: {template_data['step_count']}")
|
|
475
|
-
print(f"Automations: {template_data['automation_count']}")
|
|
476
|
-
|
|
477
|
-
# Analyze each step for improvements
|
|
478
|
-
for step_data in template_data['steps']:
|
|
479
|
-
step_id = step_data['id']
|
|
480
|
-
|
|
481
|
-
# Get dependency analysis
|
|
482
|
-
dependencies = sdk.templates.get_step_dependencies(org_id, template.id, step_id)
|
|
483
|
-
if dependencies['has_conditional_visibility']:
|
|
484
|
-
print(f"Step '{step_data['title']}' has conditional logic")
|
|
485
|
-
|
|
486
|
-
# Get deadline suggestions
|
|
487
|
-
deadline_suggestion = sdk.templates.suggest_step_deadline(org_id, template.id, step_id)
|
|
488
|
-
print(f"Suggested deadline: {deadline_suggestion['suggested_deadline']}")
|
|
489
|
-
|
|
490
|
-
# Get form field suggestions
|
|
491
|
-
field_suggestions = sdk.form_fields.suggest_form_fields_for_step(org_id, template.id, step_id)
|
|
492
|
-
for suggestion in field_suggestions[:2]: # Top 2 suggestions
|
|
493
|
-
if suggestion['confidence'] > 0.7:
|
|
494
|
-
print(f"High-confidence field suggestion: {suggestion['field_config']['label']}")
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
### Advanced Process Management
|
|
498
|
-
|
|
499
|
-
```python
|
|
500
|
-
# Get all active processes with comprehensive filtering
|
|
501
|
-
active_runs = sdk.tasks.get_organization_runs(
|
|
502
|
-
org_id,
|
|
503
|
-
status="active",
|
|
504
|
-
with_data="checklist,tasks,assets,tags",
|
|
505
|
-
form_fields_values=True,
|
|
506
|
-
starred=True
|
|
507
|
-
)
|
|
508
|
-
|
|
509
|
-
# Group by template
|
|
510
|
-
template_usage = {}
|
|
511
|
-
for run in active_runs:
|
|
512
|
-
template_id = run.checklist_id
|
|
513
|
-
if template_id not in template_usage:
|
|
514
|
-
template_usage[template_id] = {
|
|
515
|
-
'template_name': run.checklist_title,
|
|
516
|
-
'active_count': 0,
|
|
517
|
-
'runs': []
|
|
518
|
-
}
|
|
519
|
-
template_usage[template_id]['active_count'] += 1
|
|
520
|
-
template_usage[template_id]['runs'].append(run)
|
|
521
|
-
|
|
522
|
-
# Show most used templates
|
|
523
|
-
sorted_templates = sorted(template_usage.items(), key=lambda x: x[1]['active_count'], reverse=True)
|
|
524
|
-
for template_id, data in sorted_templates[:5]:
|
|
525
|
-
print(f"{data['template_name']}: {data['active_count']} active processes")
|
|
526
|
-
```
|
|
527
|
-
|
|
528
|
-
## Advanced Usage
|
|
529
|
-
|
|
530
|
-
### Custom Request Configuration
|
|
531
|
-
|
|
532
|
-
```python
|
|
533
|
-
# SDK with custom configuration
|
|
534
|
-
sdk = TallyfySDK(
|
|
535
|
-
api_key="your_api_key",
|
|
536
|
-
base_url="https://api.tallyfy.com",
|
|
537
|
-
timeout=60, # 60 second timeout
|
|
538
|
-
max_retries=5, # Retry up to 5 times
|
|
539
|
-
retry_delay=2.0 # 2 second delay between retries
|
|
540
|
-
)
|
|
541
|
-
```
|
|
542
|
-
|
|
543
|
-
### Accessing Raw API Responses
|
|
544
|
-
|
|
545
|
-
```python
|
|
546
|
-
# For advanced users who need raw API data
|
|
547
|
-
template_data = sdk.templates.get_template_with_steps(org_id, template_id)
|
|
548
|
-
raw_api_response = template_data['raw_data']
|
|
549
|
-
|
|
550
|
-
# Access nested API data not exposed in models
|
|
551
|
-
custom_fields = raw_api_response.get('custom_metadata', {})
|
|
552
|
-
```
|
|
553
|
-
|
|
554
|
-
### Batch Operations
|
|
555
|
-
|
|
556
|
-
```python
|
|
557
|
-
# Efficiently process multiple operations
|
|
558
|
-
org_users = sdk.users.get_organization_users(org_id)
|
|
559
|
-
user_tasks = {}
|
|
560
|
-
|
|
561
|
-
for user in org_users[:10]: # Process first 10 users
|
|
562
|
-
try:
|
|
563
|
-
tasks = sdk.tasks.get_user_tasks(org_id, user.id)
|
|
564
|
-
user_tasks[user.id] = tasks
|
|
565
|
-
print(f"{user.full_name}: {len(tasks)} tasks")
|
|
566
|
-
except TallyfyError as e:
|
|
567
|
-
print(f"Failed to get tasks for {user.full_name}: {e}")
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
### Form Field Automation
|
|
571
|
-
|
|
572
|
-
```python
|
|
573
|
-
# Automatically enhance templates with smart form fields
|
|
574
|
-
def enhance_template_with_smart_fields(org_id, template_id):
|
|
575
|
-
steps = sdk.templates.get_template_steps(org_id, template_id)
|
|
576
|
-
|
|
577
|
-
for step in steps:
|
|
578
|
-
# Get AI suggestions for each step
|
|
579
|
-
suggestions = sdk.form_fields.suggest_form_fields_for_step(org_id, template_id, step.id)
|
|
580
|
-
|
|
581
|
-
# Implement high-confidence suggestions
|
|
582
|
-
for suggestion in suggestions:
|
|
583
|
-
if suggestion['confidence'] > 0.8 and suggestion['priority'] == 'high':
|
|
584
|
-
field_data = suggestion['field_config']
|
|
585
|
-
try:
|
|
586
|
-
new_field = sdk.form_fields.add_form_field_to_step(
|
|
587
|
-
org_id, template_id, step.id, field_data
|
|
588
|
-
)
|
|
589
|
-
print(f"Added field '{field_data['label']}' to step '{step.title}'")
|
|
590
|
-
except TallyfyError as e:
|
|
591
|
-
print(f"Failed to add field: {e}")
|
|
592
|
-
|
|
593
|
-
# Use the enhancement function
|
|
594
|
-
enhance_template_with_smart_fields(org_id, "your_template_id")
|
|
595
|
-
```
|
|
596
|
-
|
|
597
|
-
## Contributing
|
|
598
|
-
|
|
599
|
-
### Development Setup
|
|
600
|
-
|
|
601
|
-
1. Clone the repository
|
|
602
|
-
2. Install dependencies: `pip install -r requirements.txt`
|
|
603
|
-
3. Set up environment variables in `.env`
|
|
604
|
-
4. Run tests: `python -m pytest tests/`
|
|
605
|
-
|
|
606
|
-
### Code Style
|
|
607
|
-
|
|
608
|
-
- Follow PEP 8 style guidelines
|
|
609
|
-
- Use type hints for all functions and methods
|
|
610
|
-
- Add comprehensive docstrings for public APIs
|
|
611
|
-
- Include error handling for all external API calls
|
|
612
|
-
|
|
613
|
-
### Adding New Features
|
|
614
|
-
|
|
615
|
-
1. Add methods to appropriate management class
|
|
616
|
-
2. Create or update data models in `models.py`
|
|
617
|
-
3. Add comprehensive docstrings and type hints
|
|
618
|
-
4. Include error handling and logging
|
|
619
|
-
5. Update this README with usage examples
|
|
620
|
-
|
|
621
|
-
## License
|
|
622
|
-
|
|
623
|
-
This SDK is part of the Tallyfy MCP project. See the main project repository for license information.
|
|
624
|
-
|
|
625
|
-
## Support
|
|
626
|
-
|
|
627
|
-
For bugs, feature requests, or questions:
|
|
628
|
-
|
|
629
|
-
1. Check existing issues in the project repository
|
|
630
|
-
2. Contact us at: support@tallyfy.com
|
|
631
|
-
---
|
|
632
|
-
|
|
633
|
-
**Version:** 1.0.2
|
|
634
|
-
**Last Updated:** 2025
|
|
File without changes
|
|
File without changes
|
|
File without changes
|