django-forms-workflows 0.2.0__tar.gz

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.
Files changed (49) hide show
  1. django_forms_workflows-0.2.0/CHANGELOG.md +170 -0
  2. django_forms_workflows-0.2.0/LICENSE +165 -0
  3. django_forms_workflows-0.2.0/PKG-INFO +331 -0
  4. django_forms_workflows-0.2.0/README.md +298 -0
  5. django_forms_workflows-0.2.0/django_forms_workflows/__init__.py +11 -0
  6. django_forms_workflows-0.2.0/django_forms_workflows/admin.py +434 -0
  7. django_forms_workflows-0.2.0/django_forms_workflows/apps.py +22 -0
  8. django_forms_workflows-0.2.0/django_forms_workflows/data_sources/__init__.py +79 -0
  9. django_forms_workflows-0.2.0/django_forms_workflows/data_sources/base.py +119 -0
  10. django_forms_workflows-0.2.0/django_forms_workflows/data_sources/database_source.py +242 -0
  11. django_forms_workflows-0.2.0/django_forms_workflows/data_sources/ldap_source.py +147 -0
  12. django_forms_workflows-0.2.0/django_forms_workflows/data_sources/user_source.py +73 -0
  13. django_forms_workflows-0.2.0/django_forms_workflows/forms.py +359 -0
  14. django_forms_workflows-0.2.0/django_forms_workflows/handlers/__init__.py +20 -0
  15. django_forms_workflows-0.2.0/django_forms_workflows/handlers/api_handler.py +205 -0
  16. django_forms_workflows-0.2.0/django_forms_workflows/handlers/base.py +90 -0
  17. django_forms_workflows-0.2.0/django_forms_workflows/handlers/database_handler.py +201 -0
  18. django_forms_workflows-0.2.0/django_forms_workflows/handlers/executor.py +272 -0
  19. django_forms_workflows-0.2.0/django_forms_workflows/handlers/ldap_handler.py +228 -0
  20. django_forms_workflows-0.2.0/django_forms_workflows/ldap_backend.py +424 -0
  21. django_forms_workflows-0.2.0/django_forms_workflows/management/commands/seed_farm_demo.py +377 -0
  22. django_forms_workflows-0.2.0/django_forms_workflows/management/commands/seed_prefill_sources.py +162 -0
  23. django_forms_workflows-0.2.0/django_forms_workflows/migrations/0001_initial.py +755 -0
  24. django_forms_workflows-0.2.0/django_forms_workflows/migrations/0002_prefillsource_alter_formfield_prefill_source_and_more.py +185 -0
  25. django_forms_workflows-0.2.0/django_forms_workflows/migrations/0003_postsubmissionaction.py +252 -0
  26. django_forms_workflows-0.2.0/django_forms_workflows/migrations/__init__.py +0 -0
  27. django_forms_workflows-0.2.0/django_forms_workflows/models.py +1025 -0
  28. django_forms_workflows-0.2.0/django_forms_workflows/tasks.py +263 -0
  29. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/approval_inbox.html +52 -0
  30. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/approve.html +74 -0
  31. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/base.html +119 -0
  32. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/form_list.html +38 -0
  33. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/form_submit.html +34 -0
  34. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/my_submissions.html +80 -0
  35. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/submission_detail.html +148 -0
  36. django_forms_workflows-0.2.0/django_forms_workflows/templates/django_forms_workflows/withdraw_confirm.html +38 -0
  37. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/approval_notification.html +29 -0
  38. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/approval_reminder.html +29 -0
  39. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/approval_request.html +42 -0
  40. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/email_styles.html +10 -0
  41. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/escalation_notification.html +28 -0
  42. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/rejection_notification.html +28 -0
  43. django_forms_workflows-0.2.0/django_forms_workflows/templates/emails/submission_notification.html +29 -0
  44. django_forms_workflows-0.2.0/django_forms_workflows/templates/registration/login.html +63 -0
  45. django_forms_workflows-0.2.0/django_forms_workflows/urls.py +20 -0
  46. django_forms_workflows-0.2.0/django_forms_workflows/utils.py +46 -0
  47. django_forms_workflows-0.2.0/django_forms_workflows/views.py +358 -0
  48. django_forms_workflows-0.2.0/django_forms_workflows/workflow_engine.py +290 -0
  49. django_forms_workflows-0.2.0/pyproject.toml +60 -0
@@ -0,0 +1,170 @@
1
+ # Changelog
2
+
3
+ All notable changes to Django Forms Workflows will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ### Planned Features
11
+ - Form builder UI (drag-and-drop)
12
+ - REST API for form submission
13
+ - Webhook support
14
+ - Custom field types (signature, location, etc.)
15
+ - Advanced reporting and analytics
16
+ - Multi-tenancy support
17
+
18
+ ## [0.2.0] - TBD
19
+
20
+ ### Added - Configurable Prefill Sources
21
+ - **PrefillSource Model** - Database-driven prefill source configuration
22
+ - Support for User, LDAP, Database, API, System, and Custom source types
23
+ - Flexible database field mapping with configurable lookup fields
24
+ - Custom user field mapping (employee_id, email, external_id, etc.)
25
+ - Active/inactive toggle and display ordering
26
+ - Backward compatible with legacy text-based prefill_source field
27
+ - **Enhanced Database Prefill** - Generic database lookups with custom field mappings
28
+ - Configurable DB lookup field (ID_NUMBER, EMAIL, EMPLOYEE_ID, etc.)
29
+ - Configurable user profile field for matching
30
+ - Makes library truly generic and adaptable to different deployments
31
+ - **Admin Interface** - Comprehensive admin for managing prefill sources
32
+ - Dropdown selection of prefill sources in FormField admin
33
+ - Inline editing and filtering
34
+ - Helpful descriptions and examples
35
+ - **Demo Integration** - Farm-themed demo showcasing prefill functionality
36
+ - "Farmer Contact Update" form with multiple prefill sources
37
+ - Seed command for creating demo prefill sources
38
+ - Examples of User, System, and Database prefill types
39
+
40
+ ### Added - Post-Submission Actions
41
+ - **PostSubmissionAction Model** - Configurable actions to update external systems
42
+ - Support for Database, LDAP, API, and Custom handler action types
43
+ - Four trigger types: on_submit, on_approve, on_reject, on_complete
44
+ - Flexible field mapping for all action types
45
+ - Conditional execution based on form field values
46
+ - Robust error handling with retries and fail-silently options
47
+ - Execution ordering for dependent actions
48
+ - **Database Update Handler** - Update external databases after form submission/approval
49
+ - Custom field mappings from form fields to database columns
50
+ - Configurable lookup fields and user fields
51
+ - SQL injection protection with parameterized queries
52
+ - Identifier validation for table and column names
53
+ - **LDAP Update Handler** - Update Active Directory attributes
54
+ - DN template support with placeholders
55
+ - Field mapping from form fields to LDAP attributes
56
+ - Service account integration
57
+ - **API Call Handler** - Make HTTP API calls to external services
58
+ - Support for GET, POST, PUT, PATCH methods
59
+ - Template-based request bodies with field placeholders
60
+ - Custom headers support
61
+ - Response validation
62
+ - **Custom Handler Support** - Execute custom Python code for complex integrations
63
+ - Dynamic handler loading via import_module
64
+ - Configurable handler parameters
65
+ - Standardized return format
66
+ - **Action Executor** - Coordinates execution of multiple actions
67
+ - Filters actions by trigger type
68
+ - Implements retry logic with configurable max attempts
69
+ - Comprehensive error handling and logging
70
+ - Conditional execution based on form field values
71
+ - **Workflow Integration** - Integrated with all workflow trigger points
72
+ - on_submit trigger in create_workflow_tasks()
73
+ - on_approve trigger in execute_post_approval_updates()
74
+ - on_reject trigger in approve_submission view
75
+ - on_complete trigger in _finalize_submission()
76
+ - **Admin Interface** - Comprehensive admin for managing post-submission actions
77
+ - Collapsible fieldsets for each action type
78
+ - List view with filtering and inline editing
79
+ - Helpful descriptions and examples
80
+ - **Demo Integration** - Farm demo showcasing post-submission actions
81
+ - API call action logging to httpbin.org
82
+ - Database update action example
83
+ - Both disabled by default for safety
84
+
85
+ ### Enhanced
86
+ - **Documentation** - Comprehensive guides for new features
87
+ - `docs/PREFILL_SOURCES.md` - Complete prefill configuration guide
88
+ - `docs/POST_SUBMISSION_ACTIONS.md` - Complete post-submission actions guide
89
+ - `PREFILL_ENHANCEMENTS.md` - Technical summary of prefill enhancements
90
+ - `POST_SUBMISSION_ENHANCEMENTS.md` - Technical summary of post-submission enhancements
91
+ - Updated README.md with new features
92
+ - **Farm Demo** - Enhanced example application
93
+ - Showcases both prefill and post-submission actions
94
+ - Multiple demo forms with different workflow types
95
+ - Seed commands for easy setup
96
+ - Farm-themed design for better UX
97
+
98
+ ### Security
99
+ - **SQL Injection Protection** - Enhanced database security
100
+ - Parameterized queries for all database operations
101
+ - Identifier validation for table and column names
102
+ - Whitelist-based validation
103
+ - **LDAP Security** - Secure LDAP integration
104
+ - DN template validation
105
+ - Service account permissions
106
+ - Connection encryption support
107
+ - **API Security** - Secure external API calls
108
+ - HTTPS enforcement
109
+ - API key management
110
+ - Request timeout protection
111
+ - Response validation
112
+
113
+ ### Migration Notes
114
+ - Run `python manage.py migrate` to apply new migrations
115
+ - Existing forms with text-based `prefill_source` continue to work
116
+ - New `prefill_source_config` field takes precedence when set
117
+ - Post-submission actions are opt-in and disabled by default
118
+ - No breaking changes to existing deployments
119
+
120
+ ## [0.1.0] - 2025-10-31
121
+
122
+ ### Added
123
+ - Initial release
124
+ - Database-driven form definitions
125
+ - 15+ field types (text, select, date, file upload, etc.)
126
+ - Dynamic form rendering with Crispy Forms
127
+ - Approval workflows with flexible routing
128
+ - LDAP/Active Directory integration
129
+ - External database prefill support
130
+ - Pluggable data source architecture
131
+ - Complete audit trail
132
+ - Email notifications
133
+ - File upload support
134
+ - Conditional field visibility
135
+ - Form versioning
136
+ - Draft save functionality
137
+ - Withdrawal support
138
+ - Group-based permissions
139
+ - Manager approval from LDAP hierarchy
140
+ - Conditional escalation
141
+ - Post-approval database updates
142
+ - Comprehensive documentation
143
+ - Example project
144
+
145
+ ### Security
146
+ - CSRF protection
147
+ - SQL injection prevention
148
+ - File upload validation
149
+ - Parameterized database queries
150
+ - Identifier validation for SQL
151
+
152
+ ### Dependencies
153
+ - Django >= 5.1
154
+ - django-crispy-forms >= 2.0
155
+ - crispy-bootstrap5 >= 2.0
156
+ - celery >= 5.3
157
+ - python-decouple >= 3.8
158
+
159
+ ### Optional Dependencies
160
+ - django-auth-ldap >= 4.6 (for LDAP integration)
161
+ - python-ldap >= 3.4 (for LDAP integration)
162
+ - mssql-django >= 1.6 (for MS SQL Server)
163
+ - pyodbc >= 5.0 (for MS SQL Server)
164
+ - psycopg2-binary >= 2.9 (for PostgreSQL)
165
+ - mysqlclient >= 2.2 (for MySQL)
166
+
167
+ [Unreleased]: https://github.com/opensensor/django-forms-workflows/compare/v0.2.0...HEAD
168
+ [0.2.0]: https://github.com/opensensor/django-forms-workflows/compare/v0.1.0...v0.2.0
169
+ [0.1.0]: https://github.com/opensensor/django-forms-workflows/releases/tag/v0.1.0
170
+
@@ -0,0 +1,165 @@
1
+ GNU LESSER GENERAL PUBLIC LICENSE
2
+ Version 3, 29 June 2007
3
+
4
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
5
+ Everyone is permitted to copy and distribute verbatim copies
6
+ of this license document, but changing it is not allowed.
7
+
8
+
9
+ This version of the GNU Lesser General Public License incorporates
10
+ the terms and conditions of version 3 of the GNU General Public
11
+ License, supplemented by the additional permissions listed below.
12
+
13
+ 0. Additional Definitions.
14
+
15
+ As used herein, "this License" refers to version 3 of the GNU Lesser
16
+ General Public License, and the "GNU GPL" refers to version 3 of the GNU
17
+ General Public License.
18
+
19
+ "The Library" refers to a covered work governed by this License,
20
+ other than an Application or a Combined Work as defined below.
21
+
22
+ An "Application" is any work that makes use of an interface provided
23
+ by the Library, but which is not otherwise based on the Library.
24
+ Defining a subclass of a class defined by the Library is deemed a mode
25
+ of using an interface provided by the Library.
26
+
27
+ A "Combined Work" is a work produced by combining or linking an
28
+ Application with the Library. The particular version of the Library
29
+ with which the Combined Work was made is also called the "Linked
30
+ Version".
31
+
32
+ The "Minimal Corresponding Source" for a Combined Work means the
33
+ Corresponding Source for the Combined Work, excluding any source code
34
+ for portions of the Combined Work that, considered in isolation, are
35
+ based on the Application, and not on the Linked Version.
36
+
37
+ The "Corresponding Application Code" for a Combined Work means the
38
+ object code and/or source code for the Application, including any data
39
+ and utility programs needed for reproducing the Combined Work from the
40
+ Application, but excluding the System Libraries of the Combined Work.
41
+
42
+ 1. Exception to Section 3 of the GNU GPL.
43
+
44
+ You may convey a covered work under sections 3 and 4 of this License
45
+ without being bound by section 3 of the GNU GPL.
46
+
47
+ 2. Conveying Modified Versions.
48
+
49
+ If you modify a copy of the Library, and, in your modifications, a
50
+ facility refers to a function or data to be supplied by an Application
51
+ that uses the facility (other than as an argument passed when the
52
+ facility is invoked), then you may convey a copy of the modified
53
+ version:
54
+
55
+ a) under this License, provided that you make a good faith effort to
56
+ ensure that, in the event an Application does not supply the
57
+ function or data, the facility still operates, and performs
58
+ whatever part of its purpose remains meaningful, or
59
+
60
+ b) under the GNU GPL, with none of the additional permissions of
61
+ this License applicable to that copy.
62
+
63
+ 3. Object Code Incorporating Material from Library Header Files.
64
+
65
+ The object code form of an Application may incorporate material from
66
+ a header file that is part of the Library. You may convey such object
67
+ code under terms of your choice, provided that, if the incorporated
68
+ material is not limited to numerical parameters, data structure
69
+ layouts and accessors, or small macros, inline functions and templates
70
+ (ten or fewer lines in length), you do both of the following:
71
+
72
+ a) Give prominent notice with each copy of the object code that the
73
+ Library is used in it and that the Library and its use are
74
+ covered by this License.
75
+
76
+ b) Accompany the object code with a copy of the GNU GPL and this license
77
+ document.
78
+
79
+ 4. Combined Works.
80
+
81
+ You may convey a Combined Work under terms of your choice that,
82
+ taken together, effectively do not restrict modification of the
83
+ portions of the Library contained in the Combined Work and reverse
84
+ engineering for debugging such modifications, if you also do each of
85
+ the following:
86
+
87
+ a) Give prominent notice with each copy of the Combined Work that
88
+ the Library is used in it and that the Library and its use are
89
+ covered by this License.
90
+
91
+ b) Accompany the Combined Work with a copy of the GNU GPL and this license
92
+ document.
93
+
94
+ c) For a Combined Work that displays copyright notices during
95
+ execution, include the copyright notice for the Library among
96
+ these notices, as well as a reference directing the user to the
97
+ copies of the GNU GPL and this license document.
98
+
99
+ d) Do one of the following:
100
+
101
+ 0) Convey the Minimal Corresponding Source under the terms of this
102
+ License, and the Corresponding Application Code in a form
103
+ suitable for, and under terms that permit, the user to
104
+ recombine or relink the Application with a modified version of
105
+ the Linked Version to produce a modified Combined Work, in the
106
+ manner specified by section 6 of the GNU GPL for conveying
107
+ Corresponding Source.
108
+
109
+ 1) Use a suitable shared library mechanism for linking with the
110
+ Library. A suitable mechanism is one that (a) uses at run time
111
+ a copy of the Library already present on the user's computer
112
+ system, and (b) will operate properly with a modified version
113
+ of the Library that is interface-compatible with the Linked
114
+ Version.
115
+
116
+ e) Provide Installation Information, but only if you would otherwise
117
+ be required to provide such information under section 6 of the
118
+ GNU GPL, and only to the extent that such information is
119
+ necessary to install and execute a modified version of the
120
+ Combined Work produced by recombining or relinking the
121
+ Application with a modified version of the Linked Version. (If
122
+ you use option 4d0, the Installation Information must accompany
123
+ the Minimal Corresponding Source and Corresponding Application
124
+ Code. If you use option 4d1, you must provide the Installation
125
+ Information in the manner specified by section 6 of the GNU GPL
126
+ for conveying Corresponding Source.)
127
+
128
+ 5. Combined Libraries.
129
+
130
+ You may place library facilities that are a work based on the
131
+ Library side by side in a single library together with other library
132
+ facilities that are not Applications and are not covered by this
133
+ License, and convey such a combined library under terms of your
134
+ choice, if you do both of the following:
135
+
136
+ a) Accompany the combined library with a copy of the same work based
137
+ on the Library, uncombined with any other library facilities,
138
+ conveyed under the terms of this License.
139
+
140
+ b) Give prominent notice with the combined library that part of it
141
+ is a work based on the Library, and explaining where to find the
142
+ accompanying uncombined form of the same work.
143
+
144
+ 6. Revised Versions of the GNU Lesser General Public License.
145
+
146
+ The Free Software Foundation may publish revised and/or new versions
147
+ of the GNU Lesser General Public License from time to time. Such new
148
+ versions will be similar in spirit to the present version, but may
149
+ differ in detail to address new problems or concerns.
150
+
151
+ Each version is given a distinguishing version number. If the
152
+ Library as you received it specifies that a certain numbered version
153
+ of the GNU Lesser General Public License "or any later version"
154
+ applies to it, you have the option of following the terms and
155
+ conditions either of that published version or of any later version
156
+ published by the Free Software Foundation. If the Library as you
157
+ received it does not specify a version number of the GNU Lesser
158
+ General Public License, you may choose any version of the GNU Lesser
159
+ General Public License ever published by the Free Software Foundation.
160
+
161
+ If the Library as you received it specifies that a proxy can decide
162
+ whether future versions of the GNU Lesser General Public License shall
163
+ apply, that proxy's public statement of acceptance of any version is
164
+ permanent authorization for you to choose that version for the
165
+ Library.
@@ -0,0 +1,331 @@
1
+ Metadata-Version: 2.3
2
+ Name: django-forms-workflows
3
+ Version: 0.2.0
4
+ Summary: Enterprise-grade, database-driven form builder with approval workflows and external data integration
5
+ License: LGPL-3.0-only
6
+ Keywords: django,forms,workflows,approval,form-builder,dynamic-forms,ldap,enterprise,audit,database-driven
7
+ Author: Django Forms Workflows Contributors
8
+ Author-email: opensource@opensensor.ai
9
+ Requires-Python: >=3.10,<4.0
10
+ Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Provides-Extra: all
17
+ Provides-Extra: docs
18
+ Provides-Extra: ldap
19
+ Provides-Extra: mssql
20
+ Provides-Extra: mysql
21
+ Provides-Extra: postgresql
22
+ Requires-Dist: Django (>=5.1,<6.0)
23
+ Requires-Dist: celery (>=5.3)
24
+ Requires-Dist: crispy-bootstrap5 (>=2.0)
25
+ Requires-Dist: django-crispy-forms (>=2.0)
26
+ Requires-Dist: python-decouple (>=3.8)
27
+ Requires-Dist: requests (>=2.31)
28
+ Project-URL: Documentation, https://django-forms-workflows.readthedocs.io/
29
+ Project-URL: Homepage, https://github.com/opensensor/django-forms-workflows
30
+ Project-URL: Repository, https://github.com/opensensor/django-forms-workflows
31
+ Description-Content-Type: text/markdown
32
+
33
+ # Django Forms Workflows
34
+
35
+ **Enterprise-grade, database-driven form builder with approval workflows and external data integration**
36
+
37
+ [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
38
+ [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
39
+ [![Django Version](https://img.shields.io/badge/django-5.1%2B-green)](https://www.djangoproject.com/)
40
+
41
+ ## Overview
42
+
43
+ Django Forms Workflows bridges the gap between simple form libraries (like Crispy Forms) and expensive SaaS solutions (like JotForm, Formstack). It provides:
44
+
45
+ - 📝 **Database-Driven Forms** - Forms stored in database, not code
46
+ - 🔄 **Approval Workflows** - Multi-step approval engine with notifications
47
+ - 🔌 **External Data Integration** - Pull data from LDAP, databases, APIs
48
+ - 🔒 **Enterprise Security** - LDAP/AD authentication, complete audit trails
49
+ - 🏠 **Self-Hosted** - No SaaS fees, full data control
50
+ - 🎨 **Beautiful UI** - Built on Crispy Forms and Bootstrap
51
+
52
+ ## Key Features
53
+
54
+ ### 🎯 No-Code Form Creation
55
+ Business users can create and modify forms through Django Admin without touching code:
56
+ - Drag-and-drop field ordering
57
+ - 15+ field types (text, select, date, file upload, etc.)
58
+ - Validation rules (required, regex, min/max, etc.)
59
+ - Conditional field visibility
60
+ - Custom help text and placeholders
61
+
62
+ ### 🔄 Powerful Approval Workflows
63
+ Built-in multi-step approval engine:
64
+ - Sequential or parallel approvals
65
+ - Configurable approval logic (any/all approvers)
66
+ - Email notifications and reminders
67
+ - Complete audit trail
68
+ - Approval delegation
69
+
70
+ ### 🔌 Configurable Prefill Sources
71
+ Automatically populate form fields from external systems with flexible, reusable configurations:
72
+ - **User Model** - Current user's profile data (email, name, username)
73
+ - **LDAP/Active Directory** - Enterprise directory attributes (department, title, manager)
74
+ - **External Databases** - Pull from any SQL database with custom field mappings
75
+ - **REST APIs** - Integrate with external services
76
+ - **System Values** - Current date/time, previous submissions
77
+
78
+ **New in v1.1:** Prefill sources are now configurable database records with:
79
+ - ✅ **Dropdown Selection** - Form builders select from pre-configured sources
80
+ - ✅ **Custom Field Mappings** - Configure database lookup fields for different environments
81
+ - ✅ **Reusable Configurations** - Define once, use across multiple forms
82
+ - ✅ **Centralized Management** - All sources managed in Django Admin
83
+
84
+ Example database prefill configuration:
85
+ ```python
86
+ # Admin → Prefill Sources → Add Prefill Source
87
+ Name: Student - First Name
88
+ Source Type: Database
89
+ DB Schema: dbo
90
+ DB Table: STBIOS
91
+ DB Column: FIRST_NAME
92
+ DB Lookup Field: ID_NUMBER # Column to match against
93
+ DB User Field: employee_id # UserProfile field to use for lookup
94
+ ```
95
+
96
+ See [Prefill Sources Guide](docs/PREFILL_SOURCES.md) for detailed configuration.
97
+
98
+ ### 🔄 Post-Submission Actions (NEW)
99
+ Automatically update external systems with form data after submission or approval:
100
+ - **Database Updates** - Write data back to external databases with custom field mappings
101
+ - **LDAP Updates** - Update Active Directory attributes
102
+ - **API Calls** - Send data to external services via HTTP APIs
103
+ - **Custom Handlers** - Execute custom Python code for complex integrations
104
+
105
+ **Trigger Types:**
106
+ - ✅ **On Submit** - Execute immediately when form is submitted
107
+ - ✅ **On Approve** - Execute when form is approved
108
+ - ✅ **On Reject** - Execute when form is rejected
109
+ - ✅ **On Complete** - Execute when workflow is complete
110
+
111
+ **Features:**
112
+ - Conditional execution based on form field values
113
+ - Automatic retries with configurable max attempts
114
+ - Error handling (fail silently or block submission)
115
+ - Execution ordering for dependent actions
116
+ - Complete audit logging
117
+
118
+ Example database update configuration:
119
+ ```python
120
+ # Admin → Post-Submission Actions → Add
121
+ Name: Update HR Database
122
+ Action Type: Database Update
123
+ Trigger: On Approval
124
+ DB Field Mappings:
125
+ [
126
+ {"form_field": "email", "db_column": "EMAIL_ADDRESS"},
127
+ {"form_field": "phone", "db_column": "PHONE_NUMBER"}
128
+ ]
129
+ ```
130
+
131
+ See [Post-Submission Actions Guide](docs/POST_SUBMISSION_ACTIONS.md) for detailed configuration.
132
+
133
+ ### 🔒 Enterprise-Ready Security
134
+ - LDAP/Active Directory authentication
135
+ - Role-based permissions
136
+ - Complete audit logging (who, what, when, where)
137
+ - CSRF protection
138
+ - SQL injection prevention
139
+ - File upload validation
140
+
141
+ ### 📊 Comprehensive Audit Trail
142
+ Track everything for compliance:
143
+ - Form creation/modification
144
+ - Form submissions
145
+ - Approval decisions
146
+ - Status changes
147
+ - Field value changes
148
+ - User actions with IP addresses
149
+
150
+ ## Quick Start
151
+
152
+ ### Installation
153
+
154
+ ```bash
155
+ pip install django-forms-workflows
156
+ ```
157
+
158
+ ### Basic Setup
159
+
160
+ 1. Add to `INSTALLED_APPS`:
161
+
162
+ ```python
163
+ INSTALLED_APPS = [
164
+ # ...
165
+ 'crispy_forms',
166
+ 'crispy_bootstrap5',
167
+ 'django_forms_workflows',
168
+ # ...
169
+ ]
170
+ ```
171
+
172
+ 2. Configure settings:
173
+
174
+ ```python
175
+ # Crispy Forms
176
+ CRISPY_ALLOWED_TEMPLATE_PACKS = "bootstrap5"
177
+ CRISPY_TEMPLATE_PACK = "bootstrap5"
178
+
179
+ # Forms Workflows
180
+ FORMS_WORKFLOWS = {
181
+ 'ENABLE_APPROVALS': True,
182
+ 'ENABLE_AUDIT_LOG': True,
183
+ 'ENABLE_FILE_UPLOADS': True,
184
+ 'MAX_FILE_SIZE': 10 * 1024 * 1024, # 10MB
185
+ }
186
+ ```
187
+
188
+ 3. Run migrations:
189
+
190
+ ```bash
191
+ python manage.py migrate django_forms_workflows
192
+ ```
193
+
194
+ 4. Include URLs:
195
+
196
+ ```python
197
+ urlpatterns = [
198
+ path('forms/', include('django_forms_workflows.urls')),
199
+ ]
200
+ ```
201
+
202
+ 5. Create your first form in Django Admin!
203
+
204
+ ## Architecture
205
+
206
+ ```
207
+ ┌─────────────────────────────────────────────────────────────────┐
208
+ │ User Interface │
209
+ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
210
+ │ │ Form Builder │ │ Form Viewer │ │ Approval UI │ │
211
+ │ │ (Admin) │ │ (End User) │ │ (Approvers) │ │
212
+ │ └──────────────┘ └──────────────┘ └──────────────┘ │
213
+ └─────────────────────────────────────────────────────────────────┘
214
+
215
+
216
+ ┌─────────────────────────────────────────────────────────────────┐
217
+ │ Django Application │
218
+ │ ┌──────────────────────────────────────────────────────────┐ │
219
+ │ │ Data Source Abstraction Layer │ │
220
+ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
221
+ │ │ │ LDAP │ │ Database │ │ API │ │ │
222
+ │ │ │ Source │ │ Source │ │ Source │ │ │
223
+ │ │ └────────────┘ └────────────┘ └────────────┘ │ │
224
+ │ └──────────────────────────────────────────────────────────┘ │
225
+ └─────────────────────────────────────────────────────────────────┘
226
+
227
+
228
+ ┌─────────────────────────────────────────────────────────────────┐
229
+ │ External Systems │
230
+ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
231
+ │ │ Active │ │ Legacy │ │ External │ │
232
+ │ │ Directory │ │ Databases │ │ APIs │ │
233
+ │ └──────────────┘ └──────────────┘ └──────────────┘ │
234
+ └─────────────────────────────────────────────────────────────────┘
235
+ ```
236
+
237
+ ## Use Cases
238
+
239
+ Perfect for:
240
+ - **HR Departments** - Employee onboarding, time-off requests, expense reports
241
+ - **IT Departments** - Access requests, equipment requests, change management
242
+ - **Finance** - Purchase orders, invoice approvals, budget requests
243
+ - **Education** - Student applications, course registrations, facility requests
244
+ - **Healthcare** - Patient intake, referrals, insurance claims
245
+ - **Government** - Permit applications, FOIA requests, citizen services
246
+
247
+ ## Documentation
248
+
249
+ - [Installation Guide](docs/installation.md)
250
+ - [Configuration Guide](docs/configuration.md)
251
+ - [Data Sources Guide](docs/data-sources.md)
252
+ - [Workflow Guide](docs/workflows.md)
253
+ - [API Reference](docs/api.md)
254
+ - [Architecture Overview](docs/ARCHITECTURE.md)
255
+
256
+ ## Comparison
257
+
258
+ | Feature | Django Forms Workflows | Crispy Forms | FormStack | Django-Formtools |
259
+ |---------|----------------------|--------------|-----------|------------------|
260
+ | Database-driven forms | ✅ | ❌ | ✅ | ❌ |
261
+ | No-code form creation | ✅ | ❌ | ✅ | ❌ |
262
+ | Self-hosted | ✅ | ✅ | ❌ | ✅ |
263
+ | Approval workflows | ✅ | ❌ | ⚠️ | ❌ |
264
+ | External data prefill | ✅ | ❌ | ⚠️ | ❌ |
265
+ | LDAP/AD integration | ✅ | ❌ | ❌ | ❌ |
266
+ | Audit trail | ✅ | ❌ | ✅ | ❌ |
267
+ | Open source | ✅ | ✅ | ❌ | ✅ |
268
+
269
+ ## Requirements
270
+
271
+ - Python 3.10+
272
+ - Django 5.1+
273
+ - PostgreSQL 12+ (recommended) or MySQL 8.0+
274
+ - Celery 5.0+ (for background tasks)
275
+ - Redis/Valkey (for Celery broker)
276
+
277
+ ## Contributing
278
+
279
+ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
280
+
281
+ ## License
282
+
283
+ GNU Lesser General Public License v3.0 (LGPLv3) - see [LICENSE](LICENSE) for details.
284
+
285
+ ## Support
286
+
287
+ - 📖 [Documentation](https://django-forms-workflows.readthedocs.io/)
288
+ - 💬 [Discussions](https://github.com/opensensor/django-forms-workflows/discussions)
289
+ - 🐛 [Issue Tracker](https://github.com/opensensor/django-forms-workflows/issues)
290
+
291
+ ## Roadmap
292
+
293
+ ### Phase 1: Core (Current)
294
+ - [x] Database-driven form definitions
295
+ - [x] Dynamic form rendering
296
+ - [x] Approval workflows
297
+ - [x] LDAP integration
298
+ - [x] Database prefill
299
+ - [x] Audit logging
300
+
301
+ ### Phase 2: Enhanced UX
302
+ - [ ] Form builder UI (drag-and-drop)
303
+ - [ ] Conditional field visibility (client-side)
304
+ - [ ] File upload validation
305
+ - [ ] Form templates/cloning
306
+ - [ ] Dashboard analytics
307
+
308
+ ### Phase 3: Advanced Features
309
+ - [ ] REST API for form submission
310
+ - [ ] Webhook support
311
+ - [ ] Custom field types (signature, location, etc.)
312
+ - [ ] Advanced reporting
313
+ - [ ] Form versioning
314
+
315
+ ### Phase 4: Enterprise
316
+ - [ ] Multi-tenancy support
317
+ - [ ] SSO integration (SAML, OAuth)
318
+ - [ ] Advanced RBAC
319
+ - [ ] White-label support
320
+ - [ ] Plugin marketplace
321
+
322
+ ## Credits
323
+
324
+ Built with ❤️ by the Django community.
325
+
326
+ Special thanks to:
327
+ - [Django Crispy Forms](https://github.com/django-crispy-forms/django-crispy-forms)
328
+ - [Celery](https://github.com/celery/celery)
329
+ - [django-auth-ldap](https://github.com/django-auth-ldap/django-auth-ldap)
330
+
331
+