This document describes a synchronization flow between Craft.io and a development tool, orchestrated by a client-side service, to ensure accurate, automated, and timely data transfer between the platforms.

The described synchronization flow is a recommended best practice designed for efficient and accurate data transfer. However, the Craft.io API is flexible, and customers are welcome to explore and implement alternative integration strategies that best suit their unique processes and tooling requirements.

Getting started

This synchronization process involves three main parties, each playing a distinct role in ensuring a smooth and efficient flow of information.

Craft.io API
Source of truth for product work items before development begins.
Development Tool API
Destination and management platform for work items in active development.
Client-side Sync Service
An orchestrating service responsible for reading from Craft.io, identifying ready items, pushing them to the dev tool, and (optionally) syncing updates.

Flow Description

1. Item Creation in Craft.io

Users create items (features, stories, etc.) in Craft.io.
Items may go through product refinement: spec writing, grooming, prioritization. Those stages in the process can be represented with different statuses. Products often undergo refinement, which includes stages such as spec writing, grooming, and prioritization. Each of these stages can be represented by distinct statuses.
During this stage, no API interaction with the development tool is triggered.

2. Status Update to 'Ready for Development'

When an item's status changes to "Ready for Development", it becomes eligible for sync.
This is the trigger for the client-side service to take action.

Note:

Using a status such as ‘Ready for Development’ is a recommended best practice. With that said, you can choose a different logic that works best with your organization.

3. Client-side Sync Trigger

On a scheduled basis (e.g., every 60 minutes), the client-side service calls the Craft API:

Craft.io API Call:
```
GET /workspace/{workspaceId}/items?status=Ready%20for%20Development
Headers:
x-craft-api-key: YOUR_API_KEY
```

The response will include all items with that status.
The client must track previously synced item IDs to avoid re-sending.

Note:

Make sure that you’ve completed the authentication before calling Craft.io’s API.

You can submit a request for an API key from your Craft.io admin or Craft.io support team.

4. Create items in Development Tool

For detailed instructions, please refer to the documentation available in your development tool's help center.

For each newly detected item, use the relevant POST API call to write new items.
Store the mapping between Craft item ID and development tool item ID locally for future updates.

5. Craft.io enters View-Only mode

Once an item is transferred to the development tool, Craft.io becomes view-only for that item.
Progress/status updates should be made in the development tool.

6. Optional: Sync progress back to Craft.io

The client may call Craft's API to update items with development progress:

Craft.io API Call:

PUT /workspace/{workspaceId}/items/{itemId}
Headers:
  x-craft-api-key: YOUR_API_KEY
Body:
  {
   "customFieldValues": [
    {"fieldId": "dev_status", "value": "Done"},
   ]
 }

Pro tip:

Syncing progress back to Craft.io is crucial for alignment and transparency of development work, providing product managers with real-time views and enabling accurate reporting and progress tracking.

It’s recommended to configure a listener or event trigger mechanism on the client-side service to detect when items that originated in Craft.io were updated, and if so, send an update back to Craft.io.

⚠️ Changes made directly in Craft.io after syncing may cause misalignment with the development tool. It is recommended not to modify items in Craft.io once they are managed in the development tool.

Recommendations

Maintain a sync log or database mapping Craft.io and dev tool item IDs.
Implement deduplication to avoid double posting.
Ensure field mappings (status, priority, title, etc.) are aligned across both platforms.
Include error logging and retry logic in case of API failures.

For any questions, feel free to contact Craft.io’s support team at support@craft.io.

Happy Crafting!

Integration guide - Craft.io ↔ Development Tool sync via Client Service