{"id":29396904,"url":"https://github.com/mrb101/django_steps","last_synced_at":"2026-05-18T00:32:43.307Z","repository":{"id":301704611,"uuid":"1010068396","full_name":"mrb101/django_steps","owner":"mrb101","description":"A flexible and extensible Django application for defining and managing dynamic workflows with custom steps, statuses, and CEL-based conditional transitions.","archived":false,"fork":false,"pushed_at":"2025-06-30T14:25:43.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T17:52:54.171Z","etag":null,"topics":["django","steps","transitions","workflows"],"latest_commit_sha":null,"homepage":"https://django-steps.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrb101.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T09:19:52.000Z","updated_at":"2025-06-30T14:25:46.000Z","dependencies_parsed_at":"2025-06-28T10:39:43.532Z","dependency_job_id":null,"html_url":"https://github.com/mrb101/django_steps","commit_stats":null,"previous_names":["mrb101/django_steps"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mrb101/django_steps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrb101%2Fdjango_steps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrb101%2Fdjango_steps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrb101%2Fdjango_steps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrb101%2Fdjango_steps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrb101","download_url":"https://codeload.github.com/mrb101/django_steps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrb101%2Fdjango_steps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33160477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","steps","transitions","workflows"],"created_at":"2025-07-10T12:20:18.253Z","updated_at":"2026-05-18T00:32:43.298Z","avatar_url":"https://github.com/mrb101.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Steps\n\nA flexible and extensible Django application for defining and managing dynamic workflows with custom steps, statuses, and CEL-based conditional transitions.\n\n## Overview\n\nDjango Steps is a reusable Django application that provides a robust workflow management system. It allows developers to define multi-step workflows with conditional transitions, custom step statuses, and support for essential workflow operations like pausing, resuming, and canceling.\n\nThe core idea is to provide a structured way to manage complex processes within a Django application, where a process is composed of several steps, and each step can have multiple statuses. The transitions between steps can be controlled by CEL (Common Expression Language) expressions, allowing for dynamic and flexible workflow logic.\n\n## Key Features\n\n- **Dynamic Workflows**: Define workflows with multiple steps and transitions.\n- **Conditional Transitions**: Use CEL expressions to control the flow between steps.\n- **Custom Statuses**: Define custom statuses for each step, such as \"Pending,\" \"Approved,\" or \"Rejected.\"\n- **Workflow Operations**: Pause, resume, and cancel workflow instances.\n- **Generic Association**: Link workflows to any Django model using generic foreign keys.\n- **Service-Oriented**: A dedicated service layer to interact with workflow instances.\n\n## How It Works\n\nThe application is built around a few key models:\n\n- **`Workflow`**: Represents a workflow definition, such as \"Claim Processing\" or \"User Onboarding.\"\n- **`WorkflowStep`**: Represents a single step within a workflow, like \"Submit Claim\" or \"Verify Documents.\"\n- **`WorkflowStepStatus`**: Defines a custom status for a step, such as \"Pending Review\" or \"Approved.\"\n- **`WorkflowTransition`**: Defines the transition from one step to another, with an optional CEL condition.\n- **`WorkflowInstance`**: Represents a running instance of a workflow for a specific Django model.\n\n## Usage\n\n### 1. Define a Workflow\n\nFirst, you need to define a workflow, its steps, statuses, and transitions. This can be done in the Django admin or programmatically.\n\nHere's an example of how you might define a simple \"Claim Processing\" workflow:\n\n```\n+----------------+      +----------------+      +------------------+\n|  Submit Claim  |-----\u003e|  Review Claim  |-----\u003e|  Approve/Reject  |\n+----------------+      +----------------+      +------------------+\n (Initial Step)                              (Final Step)\n```\n\n- **Workflow**: \"Claim Processing\"\n- **Steps**:\n  1. \"Submit Claim\" (Initial Step)\n  2. \"Review Claim\"\n  3. \"Approve/Reject\" (Final Step)\n\n- **Statuses**:\n  - For \"Submit Claim\": \"Submitted\" (Completion Status)\n  - For \"Review Claim\": \"Under Review\" (Default), \"Approved\" (Completion), \"Rejected\" (Completion)\n  - For \"Approve/Reject\": \"Approved\" (Completion), \"Rejected\" (Completion)\n\n- **Transitions**:\n  - From \"Submit Claim\" to \"Review Claim\" (unconditional)\n  - From \"Review Claim\" to \"Approve/Reject\" (unconditional)\n\n### 2. Start a Workflow Instance\n\nTo start a workflow for a specific object (e.g., a `Claim` model), you can use the `start_workflow_instance` service function:\n\n```python\nfrom django_steps.services import start_workflow_instance\nfrom myapp.models import Claim\n\nclaim = Claim.objects.get(id=123)\nworkflow_instance = start_workflow_instance(\n    workflow_name=\"Claim Processing\",\n    content_object=claim\n)\n```\n\n### 3. Update Step Status\n\nAs the object moves through the process, you can update the status of the current step. If the new status is a \"completion status,\" the workflow will automatically transition to the next step.\n\n```python\nfrom django_steps.services import update_workflow_step_status\n\n# This will move the workflow to the \"Review Claim\" step\nupdate_workflow_step_status(\n    workflow_instance=workflow_instance,\n    new_status_name=\"Submitted\"\n)\n```\n\nIf a transition has a condition, you can provide context data for the CEL evaluation:\n\n```python\n# Example of a conditional transition\n# Condition: \"claim.amount \u003e 1000\"\nupdate_workflow_step_status(\n    workflow_instance=workflow_instance,\n    new_status_name=\"Approved\",\n    context_data={\"claim\": {\"amount\": 1500}}\n)\n```\n\n### 4. Workflow Operations\n\nYou can also pause, resume, or cancel a workflow instance:\n\n```python\nfrom django_steps.services import (\n    set_workflow_on_hold,\n    resume_workflow_instance,\n    cancel_workflow_instance\n)\n\n# Pause the workflow\nset_workflow_on_hold(workflow_instance)\n\n# Resume the workflow\nresume_workflow_instance(workflow_instance)\n\n# Cancel the workflow\ncancel_workflow_instance(workflow_instance)\n```\n\n## Test Suite\n\nThis project uses pytest for testing. The test suite is structured as follows:\n\n- `/tests/` - The main test directory\n  - `conftest.py` - Shared pytest fixtures\n  - `test_models.py` - Tests for model functionality and validation\n  - `test_workflow_operations.py` - Tests for workflow instance operations\n  - `test_services.py` - Tests for service layer functions\n  - `pytest.ini` - Pytest configuration\n\n## Running Tests\n\nTo run the tests, use:\n\n```bash\npytest\n```\n\nOr to run a specific test file:\n\n```bash\npytest tests/test_models.py\n```\n\n## Documentation\n\nDocumentation is available in the `/docs/` directory.\n\n```bash\ncd docs\nmake html\n```\n\nThen open `_build/html/index.html` in your browser.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrb101%2Fdjango_steps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrb101%2Fdjango_steps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrb101%2Fdjango_steps/lists"}