Use this approach when you want to create a task in Fragment when an event occurs in your existing system.

​
Requirements

​
Relevant API endpoints

​
Approaches

The goal is to create a task in Fragment when an event occurs in your existing system. At a high-level, the steps are:
  1. Trigger (in your system)
  2. Create / update task (in Fragment)
Triggers could be a button click, a background job, an event emitted by a Change Data Capture (CDC) system, etc. You can create a task in Fragment and forget about it, or you can control the full task lifecycle.

​
1. Create and forget.

This is the simplest approach. You create a task in Fragment and let the Fragment workflow handle the rest. The task will be processed by your team and closed when completed. This is the recommended approach for most use cases as there is no conflict with your existing system and clear separation of concerns. Fragment is responsible for the task management, and you’re responsible for the business logic.
In this scenario, having a clear ID mapping strategy is still a good idea for idempotency reasons. See Map task IDs for more details.

​
2. Control the full task lifecycle.

In this approach, the status of the Fragment task is managed by your system. Maybe you create multiple tasks on Fragment for the same process on your side.
When controlling the full task lifecycle, ensure you:
  • Close tasks when they become irrelevant or are completed outside of Fragment
  • Update task status to reflect the current state in your system
  • Handle edge cases like duplicate task creation
  • Implement proper error handling and retry logic to maintain data consistency

​
Examples

​
Example 1: Onboarding (create and forget)

When a new user completes onboarding in your system, you can automatically create a task in Fragment to let your team know about it. In the code, it might look like this:
onboarding.py
import requests

def onboard_user(user):
    # Create user in your DB 
    db.create_user(user)

    # Create task in Fragment
    # NOTE: this can be delegated to some background job or other service that is more durable
    response = requests.post(
        "https://api.onfragment.com/api/v1/tasks",
        json={
            "fields": {
                "title": "Onboarding - {user.name}",
                "url": "https://backoffice.acme.com/users/{user.id}",
                "user_id": user.id,
                "user_name": user.name,
                "user_email": user.email,
                "user_phone": user.phone,
                "user_country": user.country,
                "user_city": user.city,
                "user_state": user.state,
                "user_zip": user.zip,
                "user_address": user.address,
            }
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "User-Agent": "acme/1.0",
        }
    )
    response.raise_for_status()

    # NOTE: we don't store the task ID nor generate it in stable way from the user ID.
    # This is just an example to illustrate the concept.
    # Even in this scenario, to avoid double creation, you could generate the task ID 
    # from the user ID and use the PUT endpoint for idempotent creation.

    # Send welcome email
    send_welcome_email(user)

​
Example 2: Workflow hooks (control the full task lifecycle)

If your system is running a multi-step workflow, you can create a task in Fragment at various steps of the process. For example, suppose your system is handling health insurance claims. Processing a claim might require multiple steps:
  1. Data entry
  2. Review
  3. Approval
  4. Payment
To track this process, you have 2 options
  1. Create a task in Fragment at each step of the process
  2. Create a single task in Fragment at the beginning of the process and update the status at each step.
It is recommended to use a hook system to create the task on Fragment if you have a workflow engine that supports hooks. This way, you can decouple the workflow execution (advance steps) from the task creation and management. Here is an example of a hook system to illustrate the concept:
workflow.py
class Step:

    def on_start(self):
        """Hook to create a task in Fragment when the step starts"""
        # Create task in Fragment
        uid = self.generate_task_uid()
        if self.requires_manual_intervention:
            response = requests.put(
                "https://api.onfragment.com/api/v1/tasks/{uid}",
                json={
                    "due_at": self.started_at.isoformat(),
                    "fields": {
                        "title": "Step 1",
                        "url": "https://backoffice.acme.com/workflows/{self.workflow_id}/steps/{self.step_id}",
                        "process_id": self.process_id,
                        "process_name": self.process_name,
                        "step_id": self.step_id,
                        "step_name": self.step_name,
                    }
                },
                headers={
                    "Authorization": f"Bearer {token}",
                    "Content-Type": "application/json",
                    "User-Agent": "acme/1.0",
                }
            )
            response.raise_for_status()

    def on_complete(self):
        """Hook to update a task in Fragment when the step completes"""
        # Close task in Fragment
        uid = self.generate_task_uid()
        response = requests.patch(
            "https://api.onfragment.com/api/v1/tasks/{uid}",
            json={
                "status": "DONE",
            },
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json",
                "User-Agent": "acme/1.0",
            }
        )
        response.raise_for_status()


workflow = Workflow(
    steps=[
        DataEntryStep(),
        ReviewStep(),
        ApprovalStep(),
        PaymentStep()
    ]
)
workflow.run(claim_id)

​
Going further

  1. It’s possible to push comments on the Fragment task. See POST /tasks/{uid}/comments for more details.
  2. It’s possible to assign a Fragment task to an operator by pushing the assignee_email in the payload (no need to map user ids). See POST /tasks for more details.
  3. It’s possible to search tasks on Fragment. See GET /tasks for more details.