This guide will walk you through the process of syncing tasks with existing objects.

​
Requirements

  • You have read the API overview guide
  • You have read the API integration guide
  • You have read the Create tasks guide
  • (optional) You have read the Map IDs guide
  • You already have a ticket/task object (from Zendesk, Jira, internal back office, etc.)

​
Relevant API endpoints

​
Approach

The goal is to create a 1:1 mapping between your existing ticket system and Fragment tasks and maintain that mapping. At the minimum, you will need to:
  1. Create a task in Fragment when a ticket is created in your existing system
  2. Push relevant changes to Fragment when the ticket is updated
In some cases, you might want to implement bi-directional sync, so that when a task is completed in Fragment, the ticket is updated in your existing system.
Fragment has experimental support for bi-directional sync, please reach out to us if you want to implement this (webhooks).

​
Overview

When you already have a ticket/task object in your existing system, you will need to create a corresponding task in Fragment. First, decide on an ID mapping strategy (see Map task IDs for more details). Second, you should push your existing object ID to Fragment as a custom field. For example,
sync.py
import requests

# Your existing ticket system
ticket = {
    "id": 123,
    "country: "FR",
}

response = requests.post(
    "https://api.onfragment.com/api/v1/tasks",
    json={
        # Optional: generate the task ID by hashing the ticket ID
        "uid": generate_uuid("123"),
        "fields": {
            "title": "Task 1",
            "url": "https://backoffice.com/tasks/1",
            "country": "FR",
            "ticket_id": 123,
        }
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "acme/1.0",
    }
)
response.raise_for_status()
task = response.json()

# Optional: store the task ID in your system
save_task_uuid(task["uid"])

​
Eventual consistency

Depending on your use case, the synchronization between your existing system and Fragment might not be immediate and only eventually consistent. To avoid consistency issues and ghost tasks, you can set an eventual consistency delay in Fragment settings. This will temporarily hide newly created tasks in the backlog for this amount of time, to let enough time for any update to be propagated to Fragment that might close the task and result in unnecessary work.