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

​
Requirements

​
Objects

  • Task: the task object

​
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. Example: onboarding a new user. 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
    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()

    # Send welcome email
    send_welcome_email(user)
To avoid double task creation and guarantee idempotency, we recommend using the PUT /tasks/{uid} endpoint instead of POST /tasks.This requires that you generate a stable task ID that is consistent across retries. 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.
It’s a good idea to read the Sync with existing objects guide.Even if you don’t have a clear 1:1 mapping between your existing system and Fragment tasks, it’s a similar setup (ID mapping, etc.).
Example: workflow hooks. 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:
            # Use PUT (idempotent)
            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)
⌘I